Skip to main content
Use the Box dashboard for secrets. Open Dashboard > Secrets and add the values your Boxes need. Dashboard secrets are applied to Boxes as:
  • environment variables, available to processes and shell sessions inside the Box
  • secret files, written under the Box work directory using the relative paths you configure
The dashboard is the preferred path for app credentials, API keys, .env files, deployment tokens, and other runtime configuration. Do not pass secrets in prompts, URLs, CLI arguments that may be logged, Docker build args, or committed files.

​
Add Environment Variables

  1. Open Dashboard > Secrets.
  2. Add shell-style lines in the environment variables editor, or replace the account secret setup programmatically. The API and SDK update is a full replacement, so send every variable and secret file that should remain configured:
box dashboard
# Open Secrets, add OPENAI_API_KEY=... and DATABASE_URL=..., then save.

curl -sS -X POST "$BOX_API_BASE/secrets" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"envContents":"OPENAI_API_KEY=...\nDATABASE_URL=postgres://...\n","secretFiles":[]}'

await box.updateSecrets({
  secretsUpdateRequest: {
    envContents: "OPENAI_API_KEY=...\nDATABASE_URL=postgres://...\n",
    secretFiles: [],
  },
});

from ascii_box_sdk.models.secrets_update_request import SecretsUpdateRequest

box.update_secrets(SecretsUpdateRequest(
    env_contents="OPENAI_API_KEY=...\nDATABASE_URL=postgres://...\n",
    secret_files=[],
))
  1. Save if you used the dashboard.
New Boxes receive the variables when they start. When you save changes, Box also pushes the updated environment to existing Boxes that are still active (provisioned, cloning, ready, idle, or running) and have a live machine connection. Stopped, archived, deleted, or unreachable Boxes pick up the latest values the next time they are started or resumed.

​
Per-Box Environment Variables

Dashboard variables apply to every Box. To give a single Box its own values, pass env when creating it: 
box new --env DATABASE_URL=postgres://... --env FEATURE_FLAG=1

curl -sS -X POST "$BOX_API_BASE/boxes" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttlSeconds":3600,"env":{"DATABASE_URL":"postgres://...","FEATURE_FLAG":"1"}}'

await box.create({
  createBoxRequest: {
    ttlSeconds: 3600,
    env: { DATABASE_URL: "postgres://...", FEATURE_FLAG: "1" },
  },
});

box.create(CreateBoxRequest(
    ttl_seconds=3600,
    env={"DATABASE_URL": "postgres://...", "FEATURE_FLAG": "1"},
))
Per-box values are merged over the dashboard variables, so a per-box key overrides a dashboard key with the same name. Keys must match [A-Za-z_][A-Za-z0-9_]* (max 128 chars), with at most 100 variables and 64KB total per Box. Reserved Box-internal names (ASCII_TOKEN, BOX_ID, and similar) are rejected. Forked Boxes inherit the source Box’s per-box variables unless the fork request passes its own env.

​
No-env Boxes

When you give Boxes to your own users, you don’t want your account’s secrets inside them. A no-env Box receives none of them: no environment variables, secret files, or credentials. It is confined to itself, so it can’t act on your account or any other Box. 
box new --no-env

curl -sS -X POST "$BOX_API_BASE/boxes" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttlSeconds":null,"noEnv":true}'

await box.create({ createBoxRequest: { ttlSeconds: null, noEnv: true } });

box.create(CreateBoxRequest(ttl_seconds=None, no_env=True))
SSH, SCP, desktop, snapshots, and public URLs all work on a no-env Box. To give one a secret of its own, pass it explicitly with env. A no-env Box can’t reach your private repositories; clone public ones, or sign in with your own credentials from inside the Box. A fork of a no-env Box is always no-env.

​
Add Secret Files

Use secret files for .env, JSON credentials, or config files that a repo expects on disk.
  1. Open Dashboard > Secrets.
  2. Add a secret file with a relative path such as ariana-ide-private/backend/.env, .env, or config/secrets.json, or update the account setup programmatically. The API and SDK update is a full replacement, so include every env var and secret file that should remain:
box dashboard
# Open Secrets, add ariana-ide-private/backend/.env as a secret file, then save.

curl -sS -X POST "$BOX_API_BASE/secrets" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"envContents":"OPENAI_API_KEY=...\n","secretFiles":[{"path":"ariana-ide-private/backend/.env","contents":"DATABASE_URL=postgres://...\n"}]}'

await box.updateSecrets({
  secretsUpdateRequest: {
    envContents: "OPENAI_API_KEY=...\n",
    secretFiles: [
      { path: "ariana-ide-private/backend/.env", contents: "DATABASE_URL=postgres://...\n" },
    ],
  },
});

from ascii_box_sdk.models.secret_file import SecretFile
from ascii_box_sdk.models.secrets_update_request import SecretsUpdateRequest

box.update_secrets(SecretsUpdateRequest(
    env_contents="OPENAI_API_KEY=...\n",
    secret_files=[SecretFile(
        path="ariana-ide-private/backend/.env",
        contents="DATABASE_URL=postgres://...\n",
    )],
))
  1. Paste the file contents and save if you used the dashboard.
Repositories selected in Dashboard > Repositories are cloned into /home/user on the hosted Box image. Folder names use the GitHub repository name, not the owner/name pair. For example, ariana-dot-dev/ariana-ide-private is cloned to: 
/home/user/ariana-ide-private
The secrets dashboard does not have a repository selector. Secret file paths are relative to the Box work directory, which is /home/user on the hosted Box image. To write a backend .env file into ariana-ide-private, include the repository folder in the path: 
ariana-ide-private/backend/.env
Box writes the file to: 
/home/user/ariana-ide-private/backend/.env
Secret file paths must be relative. Unsafe absolute paths and paths that escape /home/user are skipped.

​
Programmatic Setup

For setup scripts, configure secrets in the dashboard first, then run your setup in the Box. The script can read normal environment variables or files at the configured paths. 
box_id="$(box new --json | jq -r 'select(.event == "ready") | .id')"
box ssh "$box_id" -- bash -s < ./setup.sh

curl -sS -X POST "$BOX_API_BASE/boxes/$BOX_ID/commands" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command":"bash -lc ./setup.sh","cwd":"ariana-ide-private","timeoutSeconds":60}'

await box.command({
  boxId,
  commandRequest: {
    command: "bash -lc './setup.sh'",
    cwd: "ariana-ide-private",
    timeoutSeconds: 60,
  },
});

from ascii_box_sdk.models.command_request import CommandRequest

box.command(
    box_id,
    CommandRequest(command="bash -lc './setup.sh'", cwd="ariana-ide-private", timeout_seconds=60),
)
box ssh <id> <command> runs the command non-interactively and streams stdin, stdout, and stderr, so setup scripts do not need to be copied to a temporary path in the Box. The API and SDK command endpoint runs an already-present script or command inside the Box work directory. In Windows PowerShell, prefer running this from Node, Python, WSL, Git Bash, or cmd.exe. Native PowerShell pipelines can keep stdin open for native executables in some environments. Only use temporary uploaded env files for one-off local experiments. For normal usage, dashboard secrets keep the workflow auditable and avoid leaking values through logs or command history.