Runtime env for agent devices

Runtime env lets a platform owner define environment variables once and have them inherited by sandboxes, computers, and agent runs. Use it for provider keys, model configuration, MCP tokens, workspace defaults, and white-label customer settings that should be available automatically when a device starts or runs a command.

This is the foundation for products where users create many agent workspaces: app builders, browser operators, 24/7 company agents, research agents, and customer-specific automation fleets.

Scope model

MIOSA resolves runtime env in this order:

Precedence	Scope	Applies to
1	Tenant	Every workspace, project, sandbox, computer, and agent under the tenant
2	Workspace	Every project, sandbox, computer, and agent in that workspace
3	Project	Sandboxes, computers, deployments, and agent runs attributed to that project
4	Resource	Per-sandbox or per-computer env set directly on the resource
5	Run	Env passed directly to a single exec or agent run

More specific values override broader values with the same name. A project value overrides a workspace value; a workspace value overrides a tenant value.

Target model

Each runtime env var also has a target:

Target	Use it when
`all`	The value is safe and useful for every runtime surface
`sandbox`	The value should only appear in sandbox exec/build/agent sessions
`computer`	The value should only appear in desktop computer commands and agents
`agent`	The value should be injected into prompt-driven agent runs on sandboxes or computers

At the same scope, target-specific values override all.

Common patterns

Set ANTHROPIC_API_KEY, OPENAI_API_KEY, or product feature flags at workspace scope for one client workspace.

Set HIGGSFIELD_API_KEY or image model keys at project scope for one app or customer workflow.

Set ANTHROPIC_MODEL, MIOSA_AGENT_CWD, or MCP endpoint configuration for a class of agents.

Set deployment, registry, package manager, or private API credentials for generated builds.

CLI

Set a tenant-wide sandbox value:

miosa runtime-env set ANTHROPIC_API_KEY=sk-ant-... 
  --scope tenant 
  --target sandbox 
  --json

Set a workspace-wide computer value:

miosa runtime-env set OPENAI_API_KEY=sk-... 
  --scope workspace 
  --workspace ws_123 
  --target computer 
  --json

Set a project value for all runtime surfaces:

miosa runtime-env set HIGGSFIELD_API_KEY=higgs_... 
  --scope project 
  --project prj_123 
  --target all 
  --json

List and delete:

miosa runtime-env list --scope workspace --workspace ws_123 --json
miosa runtime-env show <env-id> --json
miosa runtime-env unset <env-id> --json

runtime-secrets is an alias:

miosa runtime-secrets list --target sandbox

Run an agent with inherited target=agent env and download the file it creates:

miosa runtime-env set ANTHROPIC_API_KEY=sk-ant-... 
  --scope project 
  --project prj_123 
  --target agent 
  --json

miosa agent run 
  --sandbox sbx_123 
  --provider claude-code 
  --cwd /workspace 
  --timeout 900 
  "Create /workspace/report.html and summarize what you built"

miosa agent-runs artifacts <run-id> --json
miosa agent-runs download <run-id> <artifact-id> --output ./report.html

SDKs

Verify inside a sandbox

Create a sandbox, wait for the VM session, then read the inherited value:

miosa sandbox create 
  --template miosa-sandbox 
  --name env-check 
  --timeout 1h 
  --json

miosa sandbox wait <sandbox-id> --json

miosa sandbox exec <sandbox-id> 
  --cmd 'printf "$ANTHROPIC_API_KEY"' 
  --json

Use --port only when you also want app preview readiness:

miosa sandbox wait <sandbox-id> --port 3000 --timeout 180 --json

Verify inside a computer

Use computers when the agent needs a desktop, browser session, GUI automation, or long-running state:

miosa computers create --name browser-agent --workspace ws_123 --json
miosa computers exec <computer-id> --cmd 'printf "$OPENAI_API_KEY"' --json

Verify inside an agent run

Agent runs are prompt-driven tasks dispatched to a sandbox or computer. They inherit target=agent env, then apply any per-run env overrides. The run record stores command metadata, status, output, events, and declared artifact paths.

Agent runtime profiles and connectors

Runtime env is one layer of the agent configuration stack:

Layer	Purpose
Runtime env	Inherited env vars and provider keys by scope and target
Agent runtime profile	Runtime choice, non-secret defaults, tools, policy, connectors
Connector	Brokered provider identity or managed account
Egress	Network policy and brokered token exchange
Agent run	One prompt/task dispatched to a sandbox or computer

Store provider keys in runtime env when the runtime expects a normal env var. Use connectors when MIOSA should broker a provider grant or managed tool.

Export generated work

When the agent creates files, download declared agent-run artifacts or export raw sandbox paths instead of scraping terminal output:

miosa agent-runs artifacts <run-id> --json
miosa agent-runs download <run-id> <artifact-id> --output ./report.pdf

miosa sandbox export <sandbox-id> /workspace/out/report.pdf 
  --output ./report.pdf 
  --json

miosa sandbox export <sandbox-id> /workspace/out 
  --label customer-deliverables 
  --output ./deliverables.tar.gz 
  --json

For live apps, expose a port or publish:

miosa sandbox wait <sandbox-id> --port 3000 --json
miosa sandbox publish <sandbox-id> --path /workspace --port 3000 --wait --json