Sandboxes (Daytona)

An agent reads and writes the files its state grants, but it runs nothing. The Daytona collection gives each session somewhere to do that: a Daytona sandbox, an isolated Linux machine the session’s tools run shell commands in and move files into and out of. Use it to analyse data with Python, convert documents, build and test a repository, or call a command-line tool.

No tool creates, starts or deletes the sandbox. The session’s first Daytona tool call creates it, every later call finds it, and Daytona stops it when the session idles and deletes it some hours after.

Daytona is an Activepieces collection archmax authors itself. Like every Activepieces collection, the deployment offers it only when the operator names daytona in the config’s activepieces section.

Before you connect

You need a Daytona organization and an API key created in Daytona’s dashboard. Give the key these permissions:

Permission	Why
write:sandboxes	Creating sandboxes. The connection test refuses a key without it.
delete:sandboxes	Replacing a sandbox that has failed.
manage:secrets	Keeping the connection’s egress secrets in Daytona. The connection test refuses a key without it when the connection has egress secrets.

The connection

Add a Daytona connection on the Connections page (see Connections and tools). Its form:

Setting	What it does
API Key	The key above. Masked, and never shown again.
API URL	Daytona’s API, https://app.daytona.io/api. Change it only for a Daytona you run yourself.
Region	The region sandboxes are created in, such as us or eu. Empty uses the organization’s default.
Snapshot	The snapshot every sandbox starts from, by name or ID: build one with the tools your agents need. Empty uses Daytona’s default snapshot.
Allowed Domains	Comma-separated domains a sandbox may connect to, such as pypi.org,files.pythonhosted.org,*.github.com. Empty keeps the organization’s network policy.
Auto-stop (minutes)	Minutes without a tool call before a session’s sandbox stops, from 1 to 1440. Default 5. See Idle stop and deletion.
Auto-delete (hours)	Hours after it stops before Daytona deletes the sandbox with its files, from 1 to 720. Default 24.
Egress Secrets	Credentials for the commands’ own API calls, which only Daytona’s egress proxy holds. See below.

What a sandbox starts from, where it runs, what it may reach, how long it lives and which credentials it has are all settings of the connection. No tool takes any of them, so neither a workflow nor a model can change them. Test reads the key’s own details from Daytona, and reports a key Daytona refuses, a missing permission, an interval out of range, or a malformed egress secret.

One sandbox per session

Each session has a sandbox of its own:

• Created on first use. The session’s first Daytona tool call creates the sandbox from the connection’s settings and starts it. That call’s result says sandbox.created and lists the egress secrets’ variables and hosts.
• Kept between calls. Every later call of the session, in this turn or one days later, runs in the same sandbox with the files it holds.
• Started again. A sandbox that stopped while the session idled or was parked is started by the next call, which waits up to three minutes for it. Its files are there; its processes are not. The result says sandbox.restarted.
• Replaced when broken. A sandbox Daytona reports in error is deleted, and a new one is created. A sandbox Daytona has deleted after its Auto-delete hours is created again the same way. Either way the result says sandbox.created, so the agent knows its earlier files are gone.
• Shared with child sessions. A child session works in its root session’s sandbox, as its files land in the root session’s folder.
• New after a setting changes. Changing the connection’s snapshot, region, allowed domains or egress secrets gives each session a new sandbox at its next call. Auto-stop and Auto-delete apply to the existing sandboxes at their next call.

Daytona labels each sandbox created-by: archmax and archmax-session with the session’s ID, so you can find a session’s sandbox in Daytona’s dashboard.

Idle stop and deletion

A sandbox costs most while it runs, so it should run only while its session uses it, but not stop between one tool call and the next of the same turn. Each such stop costs a restart of a few seconds and ends the sandbox’s processes.

• Auto-stop counts from the session’s last tool call. Daytona stops a sandbox after these minutes even while a process runs in it: only an interaction from outside resets its timer, such as a tool’s request arriving. So while a tool’s command or file transfer runs, the tool tells Daytona every 30 seconds that the sandbox is in use, and a running command is never stopped, however long it takes.
• The default, 5 minutes, is longer than the pause between a turn’s tool calls, which is the model thinking: seconds, a minute or two for a long answer. So calls in a row find the sandbox running, and a sandbox stops 5 minutes after a turn ends or parks for a decision. Lower it for agents that make quick calls, raise it for slow ones. A sandbox that stops between a turn’s calls is a sign it is too short.
• A background process does not keep the sandbox running. A job started with nohup … & ends when the sandbox stops. The tools tell the model to check on such a job within the idle minutes with a foreground command that waits and reads its log (sleep 120; tail build.log), which keeps the sandbox up while it waits.
• Auto-delete counts from the stop. After these hours Daytona deletes the sandbox with its files, and the session’s next call creates an empty one. The default, 24 hours, keeps a sandbox for a decision taken the next day; raise it for sessions that wait longer.

Every tool’s description tells the model how the sandbox lives. The result of a call that created the sandbox or started it again gives the connection’s actual numbers, as sandbox.stops_after_idle_minutes and sandbox.deleted_after_stopped_hours.

Egress secrets

A command often needs a credential: a GitHub token to clone a private repository, an API key for a service. Placed in the sandbox as an environment variable, it could be printed by any command (echo $GITHUB_TOKEN), and so read by the model, which the platform never allows for a secret. An egress secret never enters the sandbox:

1. The connection holds the secret, sealed like every secret field.
2. The tool that creates a sandbox keeps the secret in Daytona under the name archmax-<hex>, limited to the hosts you list. The name comes from a keyed digest of the variable, the hosts and the secret, so it says nothing about the secret.
3. The sandbox gets the environment variable you named, holding only Daytona’s placeholder.
4. Daytona’s egress proxy replaces the placeholder with the secret in the headers of HTTPS requests to those hosts, and scrubs the secret from their responses.

Egress Secrets is a list of rows. Add a row with the plus beside its label, and remove one with the bin at its end. Each row is:

Column	Example
Variable	GITHUB_TOKEN
Secret	the token, masked as you type it
Hosts	api.github.com, github.com

A command then uses the variable in a header, and the request carries the real secret:

curl -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/user
git -c http.extraHeader="Authorization: $GITHUB_BASIC" clone https://github.com/acme/private-repo

The second line needs a row GITHUB_BASIC whose secret is Basic followed by x-access-token:<token> in Base64.

Tell the agent in the workflow’s instructions which variables it has and what they are for.

What to know:

• Editing keeps the secrets. When you edit the connection, the rows show their variables and hosts. A Secret left blank keeps the one stored for that variable, so you can change the hosts without typing the secret again. A new row, or a renamed variable, needs its secret. Removing every row removes the egress secrets.
• Every row names its hosts. A host is exact (api.github.com) or a wildcard (*.github.com), without a scheme, path or port. A row with no hosts is refused: Daytona would send its secret to every host.
• Only HTTPS request headers. The proxy does not substitute in request bodies, query strings or plain HTTP, nor after a command transforms the placeholder: Base64-encoding user:$TOKEN sends the encoded placeholder. Store a Basic credential already encoded, as in the GITHUB_BASIC example above.
• Other hosts receive the placeholder, which is worthless outside Daytona.
• Commands can use a secret for anything it permits on its hosts. That is the point; give each token only what your agents need.
• Changing a secret makes a new Daytona secret. Sandboxes created before keep the old one, which stays in Daytona. Delete archmax-* secrets no sandbox uses in Daytona’s dashboard; each one’s description names its variable.
• Check a snapshot of your own. The proxy has to read an HTTPS request to substitute in it. Call an allowed host once from a sandbox of your snapshot and check that the call succeeds. A client that pins certificates may refuse the proxy.

Network

Allowed Domains limits every sandbox of the connection to those domains. List the hosts of your egress secrets there too. Organizations on Daytona’s tiers 1 and 2 cannot set a sandbox’s network policy: Daytona refuses to create the sandbox, and the tool reports its reason. Leave the field empty there; those organizations’ own policy applies.

The tools

Tool	What it does
daytona__execute_command	Runs a shell command and returns exit_code and output (stdout and stderr together). Past 30,000 characters the output keeps its first 10,000 and last 20,000 and says truncated. The command is stopped after timeout_seconds, default 300 and at most 3,600; longer work runs in the background with its output in a file, checked within the idle minutes (see Idle stop and deletion). cwd names the directory.
daytona__upload_file	Copies a file the agent can read, a session file or a file on a mount, to path in the sandbox. A path ending in / is a folder the file keeps its name in.
daytona__download_file	Copies the file at path into the session’s attachments and returns its reference, which the agent can pass on or copy_file onto a mount.

Relative paths resolve against the sandbox’s working directory. A file moves whole, up to 20 MiB; for a folder, the agent archives it with tar and moves the archive.

Granting the tools in a workflow

Grant the tools to the states that need them, as any connection’s (Granting a connection’s tools):

states:
  analyse:
    tools:
      allow:
        - tool: daytona__execute_command
        - tool: daytona__upload_file
        - tool: daytona__download_file
          args:
            path: ["out/*"]

upload_file’s file is governed like read_file: the state must grant the path, by its mounts or the session’s own files, or the call is refused before anything leaves. Grant it only where the files may reach Daytona. Argument guards narrow the rest, as path above lets the agent download only from out/.

Cost

Daytona bills sandboxes to your Daytona organization. They are not part of an agent’s Spend, which counts model calls. A sandbox runs only while its session uses it, plus its Auto-stop minutes, and is kept stopped for its Auto-delete hours.