Skip to content

Sandbox environment and templates ​

A template defines the software and files available to an agent. Prepare a template in your AgentBox project with Codex, the required CLI tools, skills and MCP configuration. Orpheus registers templates owned by the project identified by its AgentBox key.

  1. Define and build the environment using the AgentBox guide.
  2. Include Codex CLI and the tools your workflows need. Mattermost also requires Linux and Python 3.9 or newer. The connector installs its attachment scripts automatically.
  3. Register the template in Orpheus as described below.
  4. Use its exact catalog name in configuration.sandbox.template, a Mattermost workflow's sandbox_template, or a Space schedule.
  5. Create a new session and verify the tools.

Register a template ​

Open Settings → Templates in Orpheus Web and choose Add template. Enter the alias from your AgentBox project, for example company-agent or team/company-agent. Enter the optional tag in its separate field. Add a description to help users choose the environment. New templates are active by default.

Orpheus checks that the template and tag exist in your AgentBox project. This does not build the template, start a sandbox or check build readiness. Supply the same AgentBox key and endpoint settings to API and worker. A missing key or unavailable AgentBox prevents registration with HTTP 503. Reading, editing and deleting catalog records do not call AgentBox.

Names and tags are converted to lowercase on registration. A tag must be a tag name, not a build UUID. When the tag is omitted, registration checks default and stores the name without a suffix. Future sandboxes follow that default without pinning a build. Explicit :default remains a separate catalog entry.

The catalog is stored in PostgreSQL. Changes apply immediately without restarting API or worker. A new installation starts with an empty catalog.

Through the API ​

Send a registration request with a Bearer key:

python
import json
import os
from urllib.request import Request, urlopen

request = Request(
    os.environ["ORPHEUS_URL"] + "/api/v1/templates",
    data=json.dumps({
        "template_name": "team/company-agent",
        "tag": "stable",
        "description": "Company tools and skills",
    }).encode(),
    headers={
        "Authorization": "Bearer " + os.environ["ORPHEUS_API_KEY"],
        "Content-Type": "application/json",
    },
    method="POST",
)
with urlopen(request, timeout=20) as response:
    template = json.load(response)
print(template["id"], template["name"])

active defaults to true. A duplicate name or the same AgentBox template and tag returns 409, including when the existing record is inactive. Do not store secrets in the description.

Find and edit templates ​

The Web list shows active templates by default. Filter by activity or part of the name. Page controls and page size are at the bottom.

Open a template to edit its description or activity. Deactivation and deletion require confirmation. Name and tag cannot be edited. To use another reference, register a new record. Deleting a record removes it only from Orpheus, leaving the AgentBox template intact.

The list API accepts:

ParameterMeaning
activetrue or false. Omit to return both states
nameExact catalog name, including any team slug and tag, case-sensitive
name_containsLiteral substring, case-insensitive
limitPage size, 1–200. Default 50
cursorA returned next_cursor or prev_cursor, with unchanged filters

The two name filters cannot be combined. The response contains items, next_cursor and prev_cursor. Each page is ordered by name. Change a filter by starting from the first page. To check one stored selection, use name without an activity filter.

All SAML users and local anonymous users can manage templates. Browser writes follow the shared Origin and CSRF rules. API keys also allow management.

How activity affects sessions ​

A new session requires an active catalog entry with the exact requested name. If the catalog stores team/company-agent:stable, neither company-agent:stable nor team/company-agent selects it. A missing or inactive entry returns HTTP 422 unknown_template, with detail code template_not_found or template_inactive.

Accepted sessions keep their stored template name. Deactivation or deletion does not cancel queued work, change existing sandboxes or block continuation runs. Retrying an accepted request with its original idempotency key returns the accepted result regardless of later catalog changes.

Space keeps an inactive or deleted selection visible on the schedule. Saving other edits or resuming requires an active template. Pausing and deleting the schedule remain available.

Environment changes ​

Updating an image does not change existing sandboxes. New sandboxes use the build selected by the template name and tag. If existing Mattermost conversations need the new environment, increment the workflow revision and reload the workflow. This starts a new session on the next request. A template or tool update alone does not require a revision change. In a custom integration, create a new session when you need to replace the existing sandbox.

With allow_multiple_runs: true, files and context survive sandbox pauses between runs. In the default mode, the sandbox is deleted after its only run. Keep published results in the destination system.

Template names · Tags and versions