CLI Reference
Command reference for the `luxor` CLI covering authentication, session lifecycle, command execution, file transfer, port exposure, SSH, persistent volumes, and snapshots.
The luxor CLI drives sandboxes from the terminal. Every sandbox command lives under luxor sandbox, with luxor sbx available as a shorter alias.
Most session commands take a --session <session-id> flag. Set a current session once with luxor sandbox set <session-id> and you can omit --session on the commands that follow.
This page documents the commands used across the Sandbox docs. For the authoritative, always-current flag list, run luxor sandbox --help (or --help on any subcommand).
Authentication
# Interactive browser sign-in and workspace choice
luxor login
# Headless: print the sign-in URL instead of opening a browser
luxor login --no-browser
# Sign in with an API key (no browser), recommended for CI
luxor login --api-key lx_your_api_key
# Confirm you are signed in
luxor status
# Print the CLI version
luxor --versionBrowser sign-in creates a 30-day API key bound to the workspace you choose and stores it in the CLI. Every Sandbox command infers its workspace from that credential; the CLI does not need a separate workspace selection.
The CLI and all SDKs also read credentials from the environment:
LUXORAI_API_KEY: API key (tokens starting withlx_, ortk_for older keys, are sent asAuthorization: Bearer <token>)LUXORAI_API_ENDPOINT: override the API endpoint (defaults tohttps://api.luxor.ai; earlier CLI releases default tohttps://api.tenki.cloud, which also works)
The older TENKI_API_KEY and TENKI_API_ENDPOINT names are still read as fallbacks.
Sessions
create
Create a session and, by default, wait for it to reach RUNNING before printing the session ID.
luxor sandbox create --name demo --cpu 2 --memory-mb 4096--name <name>: human-readable session name--cpu <cores>: vCPU cores--memory-mb <mb>: memory in MB--disk-size-gb <gb>: root disk size in GB (the default is 5 GiB; use 20 GiB for coding agents that clone repositories and install dependencies)--allow-inbound: inbound exposure (preview URLs); enabled by default, pass--allow-inbound=falseto opt out--allow-outbound: outbound network calls from the guest; enabled by default--allow-domain <domain>: allow an exact hostname, a leading*.wildcard for one label, or a leading**.wildcard for any depth (repeatable; requires workspace enablement)--allow-cidr <cidr>: allow an IPv4 CIDR destination (repeatable; requires workspace enablement)--egress-policy <name>: pin a named policy from the session's workspace, merged with other egress options (repeatable; requires workspace enablement); see HTTPS request rules and saved policies--egress-intercept-https: inspect HTTPS on port 443 using the managed CA (requires allowed domains and workspace enablement)--egress-http-rule <rule>: allow HTTP requests matchingDOMAINS:METHODS[:exact=PATH|prefix=PATH|regex=PATTERN](repeatable; requires--egress-intercept-https); domains and methods are comma-separated lists--metadata <key>=<value>: attach metadata (repeatable)--env <key>=<value>: set a plaintext guest environment variable (repeatable; not secret storage)--tags <tag>: freeform tags for filtering (repeatable, or comma-separated; notkey=value)--authorized-key <key>/--authorized-keys-file <path>: SSH public keys to install in the guest--volume <volume-id>:<mount-path>[:ro]: attach a persistent volume at a mount path (append:rofor read-only)--storage-*: mount buckets from storage connections (CLI2.10.0or later); see Mount at create--storage-mount <connection>[/<prefix>]:<path>[:ro|rw]: mount a bucket on top of the workspace default mounts (repeatable)--storage-default <default-mount-id>[/[<prefix>]][:<path>][:ro|rw|default]: change one workspace default mount for this sandbox (repeatable)--exclude-storage-default <default-mount-id>: leave out one workspace default mount (repeatable)--no-storage-defaults: skip every workspace default mount
--snapshot <snapshot-id>: start from a snapshot instead of a fresh image--image <ref>: start from a published registry image,<workspace>/<artifact>[:tag](mutually exclusive with--snapshot)--max-duration <duration>: hard cap on the session's lifetime unless--stickyis set--pause-retention <duration>: how long a paused session's state is retained--sticky: discard--max-duration, report a warning, run until terminated, and keep sticky enabled across manual pause and resume--no-wait: return immediately instead of waiting forRUNNING--wait-timeout <duration>: how long to wait forRUNNINGbefore giving up--tailnet-*: join the sandbox to your Tailscale tailnet (CLI2.3.0or later); see Connect a sandbox to Tailscale--tailnet-provider tailscale: attachment provider--tailnet-auth-key-file <path>: file with the Tailscale auth key, or-for stdin--tailnet-profile-id <connection-id>: use a saved Tailscale connection instead of an auth key (CLI2.8.0or later)--tailnet-hostname <name>: device name on your tailnet--tailnet-tag <tag>: tag to request for the device (repeatable)--tailnet-ephemeral: request an ephemeral device--tailnet-wait-for-online: wait until the device is online before returning--tailnet-expose-port <port>: sandbox TCP port reachable from your tailnet (repeatable)--tailnet-accept-routes: accept subnet routes advertised on your tailnet
--no-tailnet: skip the workspace default Tailscale connection for this sandbox (CLI2.8.0or later)
# From a snapshot, with a cache volume mounted
luxor sandbox create --snapshot <snapshot-id> --volume <volume-id>:/workspace/cache
# With metadata
luxor sandbox create --metadata owner=alice --metadata job=ci-1234
# From a pre-built image
luxor sandbox create \
--image tenki/anchor:stable \
--env "ANCHOR_API_KEY=$ANCHOR_API_KEY"
# From a pre-built image (Grok)
luxor sandbox create \
--image tenki/grok:stable \
--env "XAI_API_KEY=$XAI_API_KEY"Requires the luxor CLI 1.7.0 or later.
Check your installed version with luxor --version.
Restrict outbound destinations with repeatable allowlist flags:
luxor sandbox create \
--allow-domain pypi.org \
--allow-domain '*.pypi.org' \
--allow-domain files.pythonhosted.orgUse --allow-cidr <ipv4-address>/32 to allow a single destination IP, or specify the IPv4 network prefix your service needs.
Quote wildcard domains to prevent shell expansion.
Session egress policies must be enabled for the workspace (ask support) before these flags can be used.
--allow-outbound=false blocks outbound traffic even with an allowlist, and supplied policies still undergo validation and the workspace enablement check.
Policies are fixed at create time and cannot widen workspace permissions.
See Outbound allowlists for validation rules and limits.
For a reusable registry policy and HTTP method/path restrictions, see HTTPS request rules and saved policies.
To configure additional outbound TCP ports, use the Go SDK's WithAllowedPorts example.
set
Persist a session as the current one so later commands can omit --session.
luxor sandbox set <session-id>list
List sessions. Add --json for machine-readable output.
luxor sandbox list
luxor sandbox list --jsonget
Inspect a single session.
luxor sandbox get --session <session-id>
luxor sandbox get --session <session-id> --jsonFor a session with an allowlist, the output reports allow_domains and allow_cidrs.
In JSON these are top-level arrays; empty lists are omitted.
They describe the session policy, not the combined workspace restrictions.
exec
Run a command inside a session.
# Through a shell (pipes, redirects, globs, $VAR, && and & all work)
luxor sandbox exec --session <session-id> -c 'npm ci && npm test'
# Run a program directly, with no shell
luxor sandbox exec --session <session-id> -- go test ./...-c, --shell <line>: run the line through a shell--: pass the remaining arguments to the program directly (no shell)--timeout <duration>: command timeout (e.g.2m,5m)
Streamed stdout and stderr print live, followed by the final status, exit code, and duration.
write / read
Move files in and out of the session. Paths are rooted in the working directory /home/tenki; /workspace/... paths exist only where a volume is mounted.
# Write from inline data, a local file, or stdin
luxor sandbox write --session <session-id> --path /home/tenki/app.env --data 'PORT=3000'
luxor sandbox write --session <session-id> --path /home/tenki/config.json --data-file ./config.json
echo 'hello sandbox' | luxor sandbox write --path hello.txt
# Read to stdout, or save to a local file with --out
luxor sandbox read --session <session-id> --path /home/tenki/config.json
luxor sandbox read --session <session-id> --path /home/tenki/build.log --out ./build.log
# Read a byte range
luxor sandbox read --session <session-id> --path /home/tenki/build.log --offset 1048576 --limit 4096read --out <file>: save to a local file instead of stdoutread --offset <bytes>: start reading at this byte (CLI2.10.0or later)read --limit <bytes>: read at most this many bytes (0reads to the end; CLI2.10.0or later)
With the luxor CLI 2.10.0 or later, both commands stream, so there is no file size limit.
If a read stops early, the command prints the --offset to rerun with, and with the same --out it appends the rest.
See File operations for resume behavior.
preview-url
A preview URL gives a guest port a public HTTPS address. Each preview URL belongs to the workspace, has a slug, and is bound to at most one session and port at a time.
# Create a preview URL bound to a session port
luxor sandbox preview-url create --slug my-app --session <session-id> --port 3000
# List the workspace's preview URLs, or only those bound to one session
luxor sandbox preview-url list
luxor sandbox preview-url list --session <session-id>
luxor sandbox preview-url get <preview-url-id>
# Move a preview URL to another session
luxor sandbox preview-url unbind <preview-url-id>
luxor sandbox preview-url bind --session <new-session-id> --port 3000 <preview-url-id>
# Delete a preview URL
luxor sandbox preview-url delete <preview-url-id>--slugis required oncreateand must not already be used in the workspace: 3 to 63 lowercase letters, digits, and single hyphens, starting and ending with a letter or digit; some names are reserved, and the maximum length shrinks with the length of your workspace's slug- The slug is part of the public hostname, and anyone with the URL can reach the port; for anything sensitive, add a random suffix such as
--slug "my-app-$(openssl rand -hex 12)" --sessionand--portgo together;createwithout them reserves an unbound preview URL--ttl <duration>oncreateorbindsets a lifetime, such as30mor1h; when it passes, the preview URL stops serving and is deleted- A bound preview URL must be unbound before you bind it to another session or port
- Terminating a session deletes the preview URLs still bound to it; unbind a preview URL first to keep it for another session
unbindtakes the preview URL offline but keeps it, and it counts toward the workspace's preview URL limit until you delete it- Binding can change the hostname, so use the
preview_urlprinted by the latestcreateorbind
expose, ports, and unexpose are deprecated aliases.
expose creates a preview URL with a generated slug bound to the current or given session, and unexpose unbinds every preview URL on a port without deleting them.
ssh
Open an SSH session, forward a port, or manage local SSH config and authorized keys.
# Open a shell
luxor sandbox ssh --session <session-id>
# Forward a local port to the guest
luxor sandbox ssh <session-id> -L 8080:127.0.0.1:8080
# Managed SSH config
luxor sandbox ssh config install
luxor sandbox ssh config status
luxor sandbox ssh config uninstall
# Set the guest's authorized keys
luxor sandbox ssh-keys set --session <session-id> --keys-file ~/.ssh/authorized_keyspause / resume
Pause a session to free compute while preserving its files and memory, then resume it later.
Active terminal, SSH, preview, and other TCP connections close during a pause, so reconnect after the session returns to RUNNING.
/tmp is kept across a pause but cleared when you create a snapshot. Keep logs and durable state under /home/tenki or on an attached volume.
luxor sandbox pause --session <session-id> --wait
luxor sandbox resume --session <session-id>pause returns after the request is accepted unless you pass --wait.
With --wait, it waits for PAUSED; --wait-timeout defaults to 5m.
Pause can complete before background snapshot uploads finish.
See Pausing and resuming for the storage and recovery behavior.
fork
Requires the luxor CLI v2.8.0 or later.
Create independent copies of a running session's disk and memory while the source continues running:
luxor sandbox fork <session-id> --count 2 --name-prefix experiment --wait --jsonThe source must have no attached volumes, and forking must be enabled for the workspace.
--count defaults to 1.
--count must fit the workspace's maximum children per request, which defaults to 10, and its remaining concurrent-session capacity.
CLI v2.8.0 also caps --count at 10; use v2.9.0 or later if the workspace allows more.
See Fork a running session for readiness, output fields, and cleanup.
terminate
Tear a session down.
luxor sandbox terminate --session <session-id>recover
Snapshot the disk of a sandbox that Luxor Agent Cloud terminated, for example after a crash or a failed health check.
Luxor Agent Cloud keeps that disk for 7 days.
Requires the luxor CLI 2.10.0 or later.
luxor sandbox recover <session-id>
luxor sandbox recover <session-id> --start--start: start a new sandbox from the recovered disk and make it the active session--name <name>: name the snapshot--expires-in <duration>/--expires-at <time>: when the snapshot expires--wait-timeout <duration>: how long to wait for the snapshot (default10m)
Without --start, the command prints the luxor sandbox create --snapshot <snapshot-id> command to run.
Memory and running processes are not recovered, and sandboxes you terminated yourself keep no disk.
See Recover a terminated sandbox.
Volumes
Persistent volumes belong to the API key's workspace and survive session termination.
# Create
luxor sandbox volume create --name npm-cache --size 20GB
# List, inspect, resize, delete
luxor sandbox volume list
luxor sandbox volume list --json
luxor sandbox volume get <volume-id>
luxor sandbox volume resize <volume-id> --size 40GB
luxor sandbox volume delete <volume-id>
# Attach to / detach from a running session
luxor sandbox volume attach <session-id> <volume-id> --mount /workspace/cache
luxor sandbox volume attach <session-id> <volume-id> --mount /workspace/reference --readonly
luxor sandbox volume detach <session-id> <volume-id>--name <name>: volume name--size <size>: size, accepts units (20GB,10GiB) or a plain MiB number (1024)--mount <path>: mount path when attaching--readonly: mount read-only
To attach a volume at create time instead, use luxor sandbox create --volume <volume-id>:<mount-path>[:ro].
Storage
Storage connections let sandboxes mount S3, R2, Google Cloud Storage, and S3-compatible buckets as folders.
Requires the luxor CLI 2.10.0 or later.
Connections and default mounts belong to the API key's workspace, or to the workspace you pass with --workspace <workspace-id>.
See Storage Mounts for providers, authentication, and limits.
# Connections; credential values come from --<field>-env or --<field>-file
luxor sandbox storage connections list
luxor sandbox storage connections create media --provider r2 --bucket media \
--s3-endpoint https://<account-id>.r2.cloudflarestorage.com --default-access ro \
--access-key-id-env R2_ACCESS_KEY_ID --secret-access-key-file ~/r2-secret-access-key
luxor sandbox storage connections test media
luxor sandbox storage connections update media --default-access rw
luxor sandbox storage connections delete media
# Mounts every new sandbox gets
luxor sandbox storage defaults get
luxor sandbox storage defaults set --mount media/raw:/mnt/raw:ro
luxor sandbox storage defaults set --clear
# Mounts on a running session
luxor sandbox storage mounts list <session-id>
luxor sandbox storage mounts attach <session-id> --connection media --path /mnt/media --access ro
luxor sandbox storage mounts detach <session-id> <mount-id>--provider <provider>:aws,r2,gcs, ors3for any S3-compatible service--auth <method>:access-key(the default),aws-rolefor a keyless AWS role, orr2-temporary--role-arn <arn>: IAM role in your AWS account, with--auth aws-role--access-key-id-*,--secret-access-key-*,--session-token-*,--r2-parent-token-*: each credential takes-env <variable>,-file <path>, or-secret <name>for an existings3_storagesecret--default-access ro|rw: access a mount gets unless it sets its own
Snapshots
Capture a point-in-time VM snapshot, then restore it later as a new session.
# Create from a running session (waits for READY by default)
luxor sandbox snapshot create --session <session-id> --name baseline
luxor sandbox snapshot create --session <session-id> --name with-strace --wait-timeout 10m
# List, inspect, delete
luxor sandbox snapshot list
luxor sandbox snapshot list --json
luxor sandbox snapshot get <snapshot-id>
luxor sandbox snapshot delete <snapshot-id>
# Restore as a new session
luxor sandbox snapshot restore <snapshot-id> --name restored-copy--session <session-id>: source session forcreate--name <name>: name for the snapshot or the restored session--wait-timeout <duration>: how longcreatewaits for the snapshot to becomeREADY
Snapshots capture VM state, not attached volumes, so reattach volumes explicitly when you restore. You can also create a session from a snapshot with luxor sandbox create --snapshot <snapshot-id>.
Templates
A template is a reusable definition of a prepared environment. Build it once, publish it to the registry, then create sessions from the published reference. See Templates for the full workflow.
# Define a template (only --name and --setup-script are required)
luxor sandbox template create \
--name my-node-env \
--setup-script 'curl -fsSL https://deb.nodesource.com/setup_24.x | bash - && apt-get install -y nodejs' \
--start-cmd 'node --version' \
--env NODE_ENV=production
# Build it and wait for READY
luxor sandbox template build <template-id> --wait
# List, inspect, update, delete
luxor sandbox template list
luxor sandbox template get <template-id>
luxor sandbox template update <template-id> --start-cmd 'node server.js'
luxor sandbox template delete <template-id>--name <name>: template name (required forcreate)--setup-script <script>: shell script run at build time (required forcreate)--start-cmd <cmd>: command run when a session from the template starts--env <key>=<value>: environment variable (repeatable)--cpu <cores>/--memory-mb <mb>/--disk-size-gb <gb>: default resources for sessions built from the template--tags <tag>: freeform tags for filtering (repeatable)
Templates belong to the workspace bound to the API key.
template build takes --wait (block until READY, default 15m), --wait-durable (also wait for the snapshot upload), and --wait-timeout <duration>.
Registry
The registry is a per-workspace namespace of publishable artifacts (templates or snapshots). Publishing gives an artifact a reference, <workspace>/<artifact>[:tag], that create --image accepts.
# Publish a template (or a snapshot) as a named, versioned artifact
luxor sandbox registry publish \
--image myworkspace/my-node-env:latest \
--from-template <template-id> \
--visibility private
# Browse and resolve artifacts
luxor sandbox registry list
luxor sandbox registry list --kind template
luxor sandbox registry get <workspace>/<artifact>
luxor sandbox registry resolve <workspace>/<artifact>:latest
# Create a session from a published reference
luxor sandbox create --image myworkspace/my-node-env:latest
# Release an eligible historical version's snapshot pin
luxor sandbox registry version delete myworkspace/my-node-env --snapshot-id <snapshot-id>
luxor sandbox registry version delete myworkspace/my-node-env --snapshot-id <snapshot-id> --json--image <ref>: the artifact reference to publish,<workspace>/<artifact>[:tag](required)--from-template <id>/--from-snapshot <id>: the source to publish (exactly one)--visibility <private|public|shared>: who can pull the artifact (defaultprivate)--label <label>/--title <title>/--description <text>: optional metadata
Grant cross-workspace access with luxor sandbox registry share --target-workspace <workspace-id>; remove it with unshare or share-revoke-grant.
registry version delete removes one historical registry version, not the underlying snapshot. The version must be untagged, not the latest version of the image, and unused by a share. If one of those conditions fails, publish a newer version, move the tag, or revoke the share first. Once the command succeeds, delete the released snapshot separately with luxor sandbox snapshot delete <snapshot-id>.
Use --json or --output yaml for structured output; both include image_id and snapshot_id. When a delete is blocked, the error message names the rule that stopped it, such as latest registry image version cannot be deleted or tagged registry image version cannot be deleted.