An agent opens a repository, edits two files, runs the test suite, and waits for the result. The browser tab closes while the test is still running. When the developer returns, the product needs to reconnect to the same work, show the failed command, and explain which files changed.
That workflow is why an AI dev container is more than a Docker image with a model attached. The container is one execution boundary. The production agent runtime, the software that controls an agent session, also has to own session identity, command results, cleanup, credentials, and the record a reviewer sees after the run.
An AI dev container is an isolated development workspace where an agent can read files, run commands, edit code, and leave artifacts. An agent runtime is the software that starts and supervises the agent inside that workspace. A trace is the record of the run’s inputs, actions, tool calls, outputs, and failures.
Tangle Sandbox provides a public software development kit (SDK) for creating that workspace, running commands, dispatching agent prompts, and reconnecting to durable sessions. This article explains the production boundary around those calls and shows the smallest public smoke test.
A production AI dev container is ready when a reviewer can reconnect to the work, inspect the evidence, and recover from a failed step without giving the agent the host machine.
The container is part of the runtime
A local container can run a command. A production agent product must answer several additional questions.
| Boundary | Question a product must answer |
|---|---|
| Isolation | Can one run read or change another run’s files? |
| Filesystem | Where do source files, generated files, and snapshots live? |
| Commands | Are stdout, stderr, exit code, timing, and timeout preserved? |
| Sessions | Can a client reconnect after a browser reload or service deploy? |
| Credentials | Which process can read each secret, and does it enter an artifact? |
| Evidence | Can a reviewer see the diff, commands, tests, and failures? |
| Cleanup | What disappears when the task ends, and what is retained? |
Those questions describe a control plane around the container. The control plane is the software that creates the workspace, routes commands to it, records state, and closes it. It should not ask the model to remember its own security boundary.
The Tangle Sandbox documentation describes a sandbox as a dev container or microVM with a shell, filesystem, ports, snapshots, and an optional GPU. A microVM is a small virtual machine with a stronger machine boundary than an ordinary process container. Both are implementation choices behind the same product-level contract.
The isolation primitive still matters. Firecracker documents a microVM monitor with a small device model and a separate virtual-machine boundary. The Open Container Initiative runtime specification defines a standard interface for launching containers. Docker’s security guide explains the limits and controls around containerized processes. None of those sources supplies session replay, agent-specific evidence, or a review decision. The product has to build those layers.
Start with a public smoke test
The current public SDK quickstart uses a server-side TypeScript client. Install the package and keep the API key out of browser code.
npm install @tangle-network/sandbox
export TANGLE_API_KEY=sk-tan-...The smallest real call creates a machine, runs one harmless command, inspects the result, and releases the machine:
import { Sandbox } from '@tangle-network/sandbox'
const client = new Sandbox({
apiKey: process.env.TANGLE_API_KEY!,
baseUrl: process.env.SANDBOX_BASE_URL ?? 'https://sandbox.tangle.tools',
})
const box = await client.create({
image: 'universal',
name: 'agent-smoke',
})
try {
const result = await box.exec('node --version && npm --version')
console.log({
exitCode: result.exitCode,
stdout: result.stdout,
stderr: result.stderr,
})
} finally {
await box.delete()
}This example uses the public Sandbox quickstart and SDK reference. The result is useful because it exposes an exit code and output rather than returning a generic “command accepted” message.
The smoke test does not prove that your repository image is correct. It does not prove that a credential is scoped correctly. It does not prove that a long-running agent can reconnect. It proves only that the client can create the selected public environment, execute one command, and delete it.
Run this test before adding a model, browser, repository clone, or customer data. A failure at this boundary is cheaper to fix than a failure hidden inside a long agent task.
The server owns the lifecycle
The SDK creates and controls the workspace, but the application still needs a state model around it. A browser should not decide that a sandbox is ready because the create request returned. The server should wait for the environment to accept commands and should persist the identifiers needed to reconnect.
One useful application state sequence is:
requested -> creating -> ready -> running -> reconnecting
| |
v v
failed retaining -> deletedThe names are illustrative. The important properties are that “ready” means a real command can run, “failed” retains the creation error, and “deleted” is not confused with “evidence deleted.” The review packet should live outside the temporary machine if a reviewer needs it after cleanup.
Readiness should come from a harmless command with the expected working directory and executable, not from a successful control-plane response alone. If that command cannot run, keep the machine in a creating or failed state and retain the reason. This prevents the first agent prompt from becoming an accidental readiness test with user data attached.
Persist at least the application run identifier, sandbox identifier, session identifier when there is one, creation time, expiration policy, and cleanup state. Do not use a browser tab or an in-memory promise as the only record of ownership. When the API worker restarts, it should be able to answer whether the machine exists and whether a session is already in flight.
The SDK’s idempotent session dispatch helps with one retry boundary. It does not make sandbox creation idempotent by itself. If a create request times out after the service accepted it, the application needs its own request identity or a lookup strategy before creating another machine. Otherwise, a network retry can leave two workspaces running the same task.
Cleanup needs the same care. Delete only after durable evidence has been stored, and make cleanup retryable without hiding the original task result. If deletion fails, label the machine for later cleanup rather than telling the reviewer that the run is gone.
A real run has more than one lifecycle
A short command and a long agent task have different lifecycles.
For a command, the important sequence is:
create -> execute -> inspect exit code and output -> deleteFor an agent task, the sequence is closer to:
create -> dispatch -> stream -> reconnect -> inspect files and tests -> retain evidence -> deleteThe second sequence needs a stable session identity. The Tangle SDK reference exposes a durable session path with dispatch, event consumption, result retrieval, and status inspection.
const { sessionId, alreadyExisted } = await box.dispatchPrompt(
'Run the tests and summarize any failure without changing files.',
{ sessionId: serverDerivedSessionId },
)
console.log({ sessionId, alreadyExisted })
for await (const event of box.session(sessionId).events()) {
console.log(event)
}
const final = await box.session(sessionId).result()
const state = await box.session(sessionId).status()
console.log({ final, state })The session identifier should be derived by the server. The SDK reference says that reusing the same identifier makes a repeated dispatch idempotent, so a retry returns the in-flight or completed session instead of executing the work twice. That property matters when the caller is a webhook, a background worker, or a browser that lost its connection.
The stream is not the source of truth for every artifact. Keep the session events, final result, file diff, test reports, and retained snapshot or output reference together under the same application run identifier. If a product stores only the last streamed sentence, it cannot reconstruct what happened during the command that produced the patch.
Evidence should survive the workspace
A disposable workspace is allowed to disappear. The review record is not.
For a coding task, a useful evidence packet can contain:
{
"runId": "run_2026_08_03_dependency_update",
"sessionId": "session_derived_by_server",
"commands": [
{
"command": "npm test",
"exitCode": 1,
"stdout": "12 passed, 1 failed",
"stderr": "",
"timedOut": false
}
],
"changedFiles": ["package.json", "package-lock.json"],
"checks": [
{
"name": "unit tests",
"status": "failed",
"evidence": "command-1"
}
],
"decision": "needs-review"
}This JSON is an illustrative application record. It is not a claim about the exact Sandbox response schema.
The record keeps four things separate:
- What the agent attempted.
- What the environment returned.
- What files or artifacts changed.
- What a product or reviewer decided.
A review decision is not a model output. It is an explicit acceptance, rejection, or request for more evidence. An evaluation is a repeatable check against a criterion, such as whether tests pass or a required file exists. The evaluation can feed the review decision, but a passing command does not automatically authorize a merge.
Tangle’s Intelligence product is the analysis layer that can receive run traces and help explain why a run failed. The current Tangle AI documentation describes that relationship between sandbox runs, traces, and evaluation. The trace is evidence about the run. It is not proof that the generated code is safe.
Make review artifacts deterministic
A reviewer should be able to answer the same questions after the workspace is gone. What did the agent start from? What did it change? Which commands ran? What did each command return? Which checks were required, and which were skipped?
A durable review packet can point to immutable artifacts rather than copying every byte into one database row:
{
"base": { "artifact": "workspace-snapshot-before" },
"diff": { "artifact": "patch-17", "files": 2 },
"commands": [
{ "id": "command-1", "name": "npm test", "exitCode": 1 },
{ "id": "command-2", "name": "npm test", "exitCode": 0 }
],
"requiredChecks": ["unit tests", "type check"],
"missingChecks": ["type check"],
"decision": "needs-review"
}This is an illustrative application record, not the Sandbox SDK response schema.
The stable command identifiers let a check result cite the exact output that supports it.
The missingChecks field prevents a passing unit test from being read as a complete review.
The base artifact gives the reviewer a comparison point even when the agent rewrote files several times.
The packet should also record whether output was truncated or a command timed out. A short stdout string can mean “the command was quiet” or “the runtime stopped capturing output.” Those are different explanations for a missing fact. When an artifact is redacted for a secret, record that redaction rather than presenting the shortened artifact as complete.
Production policy belongs outside the prompt
An agent prompt can ask for a limited action. It cannot enforce a process boundary after the model decides to try something else.
Write the policy that surrounds the task:
| Policy item | Example rule |
|---|---|
| Command budget | Stop a command after a fixed time and retain partial output |
| Filesystem | Keep writes inside the run workspace and exclude host credentials |
| Network | Allow only the package or service destinations the task needs |
| Secrets | Mount short-lived credentials only into the process that needs them |
| Image | Pin or inspect the base image used by the run |
| Session lifetime | Stop idle work and cap total lifetime |
| Artifact boundary | Remove secrets from logs and preserve the diff separately |
| Cleanup | Delete the machine unless a reviewed snapshot or artifact must remain |
The exact rules depend on the product. The invariant is that the runtime enforces them independently of the model’s prose.
The first failure case to test is a rejected command. Ask the worker to perform an action outside the policy and make sure the result says rejected, names the rule, and leaves a record. The second is a failed command. Make sure a non-zero exit code and partial output remain available for review. The third is a lost client. Make sure the same session can be reopened without starting another worker.
When the container becomes a Tangle service
A sandbox can remain a managed development environment. It can also become one component in a protocol-backed service. The terms are easy to mix up.
A Blueprint is a reusable service template with a defined job interface and execution requirements. A service instance is one live deployment of that template. An operator is the compute provider that runs a service instance. An operator can host the service without being the developer who wrote its Blueprint. The Tangle core concepts explain that relationship.
A router is the model-access layer that chooses or forwards inference requests. It can make model access consistent across a product, but it does not replace workspace policy.
x402 is a payment protocol for paid HTTP requests between software systems. It can authorize a paid task before the sandbox begins, but a settled payment does not prove that the task succeeded. The x402 specification and implementations describe the payment boundary.
Attestation is cryptographic evidence about a confidential machine or protected execution image. It can help a caller check where code ran. It does not prove that the agent chose the right edit or that a test suite covered the right behavior. Tangle’s runtime and backend documentation requires attestation before its confidential runtime mode is activated.
These layers answer different questions:
| Layer | Question it can answer |
|---|---|
| Sandbox | Where did the commands and file edits run? |
| Trace | What did the runtime record during the run? |
| Evaluation | Did the result satisfy the declared check? |
| Blueprint | What reusable service interface is being offered? |
| Operator | Who supplied the compute for the service instance? |
| Attestation | Which protected execution environment made a claim? |
| x402 | Was the HTTP payment flow settled? |
No row by itself proves that a code change should ship.
A dev container has limits
A container or microVM reduces the area a mistake can affect. It does not remove every security risk.
An allowed network route can still send private data. A broad credential can still authorize a destructive API call. A malicious dependency can still run during installation. A compromised base image can undermine the application above it. A model can make an incorrect edit that passes a weak test. A trace can be incomplete even when the process exits zero.
The product should make those failures visible and give a reviewer a recovery action. “Command failed, files changed, tests missing, review required” is a better state than “agent completed” when the evidence is incomplete.
The AI agent sandbox guide explores the smaller workspace boundary. The AI agent runtime environment guide maps the sandbox to model routing, browser actions, service execution, and payment without treating any one surface as proof of correctness.
Decide what to run
Use a local container when the developer owns the machine and the task does not need hosted sessions. Use a short-lived code runner when the input and output are fixed and no intermediate workspace needs to survive. Use a managed AI dev container when an agent must edit real files, run several commands, recover from failure, or leave a record for review. Add durable sessions when clients can disconnect. Add retained artifacts when the workspace can be deleted. Add evaluation and approval when the result can affect production code, money, or customer data.
The right smoke test is small. Create one sandbox, run one harmless command, dispatch one read-only task, force one failure, reconnect, inspect the evidence, and clean up. If a team cannot explain that run, a larger autonomous workflow will hide more failure than it solves.
What is an AI dev container?
An AI dev container is an isolated development workspace where an agent can read and write files, run commands, and preserve the output needed for review.
Is an AI dev container the same as Docker?
No. Docker can supply one process-isolation layer. An agent runtime also needs sessions, command records, file state, cleanup, credentials, and a review path.
What does Tangle Sandbox add?
The public SDK creates a workspace, runs commands, dispatches agent prompts, exposes durable sessions, and releases the machine when the work ends. The surrounding product still decides what to retain and how to evaluate the result.
Does a trace prove that the agent made a good change?
No. A trace shows what the runtime recorded. Tests, policy checks, review, and task-specific evaluation decide whether the change is acceptable.
When should I use a managed AI dev container?
Use one when the agent needs real files or processes and the client may disconnect before the work ends. Use a smaller local or one-shot runner when no persistent workspace or review record is required.
When the workspace must survive reconnects and expose a longer-lived agent session, continue with LLM Sandbox Environments for Agent Runs.