Sandboxes

A sandbox is a Linux environment for a job: an image, resource limits, a wall-clock budget, and an egress policy. The default image alias is tachyonic.sh/base. Sandbox commands require CLI 0.18.0 or later.

Lifecycle

A sandbox moves through creation, readiness, and stopping to a stopped or failed state. It stops when you remove it, its budget runs out, or it fails. Its record and lifecycle events remain after stopping.

tachyonic sandbox get sb_example
tachyonic sandbox events sb_example
tachyonic sandbox rm sb_example

Use the ID returned by create in place of sb_example throughout this guide.

Isolation

Container isolation shares the host kernel. Resource limits and network policy are controls for the job, not a guarantee that arbitrary code is safe.

The sandbox record reports its selected isolation and placement. An explicit --isolation container or --isolation microvm requirement is never silently downgraded. If no matching pool is available, creation fails with capacity_unavailable. --isolation any permits the service to choose.

Check tachyonic regions for currently available pools. A listed region does not promise that every isolation option has capacity there.

Egress

The sandbox gateway applies the selected outbound policy:

The default policy is allowlist. Its package and source hosts support common installation workflows. Add only what your job needs:

tachyonic sandbox create --budget 30m --egress allowlist --allow api.example.com

--allow accepts a hostname, a wildcard such as *.example.com, or an IP address. Policy enforcement does not currently provide a customer egress-log viewer. Lifecycle and command events are separate from an egress trace.

Budgets and sizes

--budget 30m sets a wall-clock limit. --budget-usd adds a dollar limit; budget thresholds appear in lifecycle events. The sandbox stops when the trusted meter confirms that limit. Before a trusted reading, an estimated upper bound can warn without stopping the sandbox.

tachyonic sandbox create --cpu 1 --memory 1g --disk 10 --budget 30m
tachyonic sandbox create --budget 30m --budget-usd 1

Each plan caps concurrent sandboxes, session length, CPU, memory, and disk. Read the current pricing and plan limits. Requests beyond a plan limit fail; a full concurrency limit requires waiting for a sandbox to stop.

Set a workspace monthly budget with a key that has budget:write:

tachyonic budget get
tachyonic budget set --monthly 200 --action stop

stop prevents new starts and stops running sandboxes at the limit. alert records budget warnings. Device-login keys lack budget:write, so a key that runs jobs cannot raise its own budget. Create a separate appropriately scoped key in the console when you need to manage the limit.

TACHYONIC_CPUS reports the sandbox's allocated CPUs, rounded up. Thread-pool environment variables are set to the same count. A program that inspects the host directly can report a larger CPU count than the sandbox allocation.

Commands and files

tachyonic sandbox exec sb_example --cwd /workspace -- python3 --version
tachyonic sandbox shell sb_example
tachyonic sandbox cp ./report.json sb_example:/workspace/report.json
tachyonic sandbox cp sb_example:/workspace/report.json ./downloaded-report.json

exec -i sends stdin. --cwd sets the command directory and --timeout bounds the command. shell opens an interactive PTY. cp copies a file; for a directory, stream an archive:

tar -cf - ./src | tachyonic sandbox exec -i sb_example -- tar -xf - -C /workspace

Relative sandbox paths are under /workspace. Storage is ephemeral; copy out files you need before stopping the sandbox. Do not put credentials in --env arguments; process listings and shell history can expose them.

Events, usage, and regions

tachyonic sandbox events sb_example --follow
tachyonic sandbox usage sb_example
tachyonic usage
tachyonic usage --month 2026-09
tachyonic regions

Usage reports show measured quantities, estimated cost, included credits, and billable usage. Published rates are expressed per hour; meters accumulate usage by the second. A capacity request may need to start a node, so readiness can take several minutes.

Next

• Sandbox quickstart
• Sandbox CLI
• Sandbox API
• Security runtimes