Containers

Beta

BetaServer tools are currently in beta. The API and behavior may change.Sandbox containers work on the global endpoint (openrouter.ai) only. Requests through the in-region endpoints (eu.openrouter.ai, us.openrouter.ai) return an error.

A container is an isolated Linux environment. The shell and bash server tools run their commands inside a container. Each container has its own file system. The files in the container’s home directory are saved after every command, so a later request can reuse them.

Container ids

Every container has an id. The id can be set in the server tool’s environment configuration. Shell and bash tool results return the id in their container_id field. There are two modes of configuring the container, container_auto and container_reference:

{
  "type": "openrouter:shell",
  "parameters": {
    "environment": { "type": "container_auto" }
  }
}

{
  "type": "openrouter:shell",
  "parameters": {
    "environment": { "type": "container_reference", "container_id": "my-project" }
  }
}

Automatic ids (`container_auto`)

This is the default when you omit environment. The id depends on your request:

When the request has a session id, the container id is sess_ plus the session id. All requests with the same session id share one container.
When the request has no session id, the container id is gen_ plus a hash of the request id. Each request gets its own container.

We treat all of these as session ids, in this order:

The session_id field in the request body.
The x-session-id request header.
The prompt_cache_key field in the request body.

A session id must use only letters, digits, _, and -. An id with other characters is ignored, and the request falls back to a per-request container. When the session id is longer than 20 characters, only the last 20 characters are used.

Your own ids (`container_reference`)

With container_reference, you can pass a container_id from another session, or pass a custom container id. The id must be 1 to 40 characters and use only letters, digits, _, and -. Every request with the same id reaches the same container and the same files. Containers are scoped to your workspace. Two workspaces can use the same id without seeing each other’s files.

One id, two tools

The shell tool and the bash tool use separate compute environments, even for the same container id. They share the same saved files.

Container lifetime

A container sleeps after it has been idle. The sleep_after_seconds setting controls the idle time:

The default is 900 seconds (15 minutes).
The maximum is 14,400 seconds (4 hours).
Each command resets the timer.

Sleep does not delete the files in the home directory. When a request with the same container id arrives later, a new sandbox starts and loads the saved files first. Open processes, environment variables, and installed system state are not restored.

File persistence

Commands run in /home/sandbox, which is also the home directory. After every command, the changed files under the home directory are saved to storage. Deleted files stay deleted. Files outside the home directory are not saved. Each tool result reports the files the command created or changed, in the files field:

{
  "type": "openrouter_shell_tool_result",
  "container_id": "sess_abc123",
  "files": [
    {
      "type": "container_file_citation",
      "container_id": "sess_abc123",
      "file_id": "cfile_b3V0L3JlcG9ydC5jc3Y",
      "filename": "out/report.csv",
      "start_index": 0,
      "end_index": 0
    }
  ],
  "content": [ ... ]
}

The list contains at most 10 files. When a command changes more than 10 files, the 10 most recently changed files are reported. Deleted files are not reported.

Attach workspace files

You can copy files from your workspace into a container before the first command runs. First upload the files with the Files API. Then pass their ids in the file_ids field of the container environment:

{
  "type": "openrouter:shell",
  "parameters": {
    "environment": {
      "type": "container_auto",
      "file_ids": ["or_file_011CNha8iCJcU1wXNR6q4V8w"]
    }
  }
}

Rules:

You can attach up to 20 files.
Each file appears in the home directory as a writable copy. The copy is named with the last 8 characters of the file id, a -, and the base filename. A file stored as data/report.csv with an id ending in NR6q4V8w appears as ~/NR6q4V8w-report.csv. This prefix keeps two files with the same name apart.
The copy is independent. Changes inside the container do not change the workspace file.
An unknown or malformed file id fails the request with a 400 error before any command runs.

Download container files

Files created inside a container can be downloaded through the container files endpoints. List the files in a container:

{
  "object": "list",
  "data": [
    {
      "id": "cfile_b3V0L3JlcG9ydC5jc3Y",
      "object": "container.file",
      "container_id": "sess_abc123",
      "bytes": 123,
      "created_at": 1755640000,
      "path": "out/report.csv",
      "source": "assistant"
    }
  ],
  "first_id": "cfile_b3V0L3JlcG9ydC5jc3Y",
  "last_id": "cfile_b3V0L3JlcG9ydC5jc3Y",
  "has_more": false
}

GET /api/v1/containers/{container_id}/files lists the files. The limit parameter sets the page size, from 1 to 1000 (default 100). Use the after parameter with a file id to get the next page.
GET /api/v1/containers/{container_id}/files/{file_id} returns the metadata of one file.
GET /api/v1/containers/{container_id}/files/{file_id}/content streams the file content.

Container file ids start with cfile_. They encode the file path, and they match the file_id values in the tool result’s files field.

Save a container file to your workspace

Container files live with the container. To keep a file for the long term, promote it to a workspace document:

{
  "id": "or_file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file",
  "filename": "out/report.csv",
  "mime_type": "text/csv",
  "size_bytes": 123,
  "created_at": "2026-08-25T00:00:00Z",
  "downloadable": false
}

POST /api/v1/containers/{container_id}/files/{file_id}/promote copies the file into your workspace documents. The response is the new document in the Files API shape, with a new or_file_ id. You can then use the new id like any uploaded file, for example in file_ids. Rules:

The copy is independent. The container file stays in the container, and later changes to it do not change the document.
The document keeps the container file path as its filename.
Files larger than 100 MiB return a 413 error.
Any content the sandbox produced is accepted. The file type is read from the content; unknown content is stored as binary data.
Like uploaded files, the new document cannot be downloaded through the Files API. Download the container file through the content endpoint first if you need the bytes.

Network access

By default, a container has no outbound internet access. The network_policy setting can allow specific domains. See the shell network policy and bash network policy sections.

Limits

Limit	Value
Commands per tool call	100
Characters per command	16,384
Command timeout (`timeout_ms`)	Default 120,000 ms, maximum 300,000 ms
Output per stream (`max_output_length`)	Default 16,384, maximum 65,536 characters
Idle sleep (`sleep_after_seconds`)	Default 900 s, maximum 14,400 s
Attached workspace files	20
Reported changed files	10 per command
Server tool calls per request	30

Next steps

Shell: The shell server tool
Bash: The bash server tool
Files API: Upload files to your workspace

Overview

Models & Routing

Tool Calling

Features

Ori

Privacy

Best Practices

Community

Container ids

Automatic ids (`container_auto`)

Your own ids (`container_reference`)

One id, two tools

Container lifetime

File persistence

Attach workspace files

Download container files

Save a container file to your workspace

Network access

Limits

Next steps

​Container ids

​Automatic ids (container_auto)

​Your own ids (container_reference)

​One id, two tools

​Container lifetime

​File persistence

​Attach workspace files

​Download container files

​Save a container file to your workspace

​Network access

​Limits

​Next steps

Container ids

Automatic ids (`container_auto`)

Your own ids (`container_reference`)

One id, two tools

Container lifetime

File persistence

Attach workspace files

Download container files

Save a container file to your workspace

Network access

Limits

Next steps