Amodal Configuration
Amodal has two configuration scopes:
- Agent workspace pages live under
/agents/:agentId/*and configure one agent. - Organization workspace pages live under
/org/:orgId/*and configure members, billing, model provider credentials, and automation tokens.
Permissions decide what each member can see and edit. Viewers see read-only versions of pages that admins and developers can edit.
Agent Workspace
The sidebar groups agent pages into Operate, Deploy, Resources, and Configure.
| Page | Path | What it shows |
|---|---|---|
| Overview | /agents/:id | Health summary, recent sessions, billable spend, model status, connection gaps, and suggested actions. |
| Sessions | /agents/:id/sessions | Saved conversations with scopes, token usage, messages, and tool calls. |
| Traces | /agents/:id/traces | Recorded runs, trace sessions, monitoring, and online evaluators. |
| Issues | /agents/:id/issues | Recurring failures that triage found in flagged production runs. See Issues. |
| Activity | /agents/:id/activity | Audit events such as deploys, source commits, auth changes, and secret edits. |
| Logs | /agents/:id/logs | Runtime logs filtered by level, scope, session, and text. |
| Cost | /agents/:id/cost | Estimated model spend by scope, model, deploy, and day. |
| Source | /agents/:id/files | Source browser and editor for Amodal-hosted versions or a connected Git repository. |
| Deploys | /agents/:id/deploys | Deploys, build logs, and promote, start, stop, redeploy, and delete actions. |
| Evals | /agents/:id/evals | Eval cases and runs, including model comparison. See Evals. |
| Connections | /agents/:id/connections | Connection inventory, credential status, runtime health, and route probes. |
| Guardrails | /agents/:id/guardrails | Connection policy, field restrictions, and safety configuration from source. |
| Automations | /agents/:id/automations | Platform-managed background bindings and their runs. |
| Stores | /agents/:id/stores | Store schemas and documents. |
| Knowledge | /agents/:id/knowledge | Knowledge entries, including corpora and libraries, and the documents filed in a library. |
| Memory | /agents/:id/memory | Memory entries when memory is enabled. |
| Feedback | /agents/:id/feedback | End-user feedback review queue. |
| Settings | /agents/:id/settings/general | See Settings. |
| Models | /agents/:id/models | See Models. |
| Prompt | /agents/:id/prompt | Compiled system prompt, token budget, and the largest prompt contributors. |
| Embed | /agents/:id/embed | See Embed. |
Traces > Sessions can list sessions that have no saved conversation. These rows show Conversation unavailable, and their runs remain available.
Under Traces > Evaluators, online evaluators grade recorded runs. Choose an LLM judge with a rubric, or TypeSafe Jev with a statement or scoring rubric. TypeSafe Jev can escalate uncertain results to an LLM judge. Set a sampling percentage and filter eligible runs by source, status, model, or tool.
Cost estimates model spend from trace spans. It excludes platform fees and reports runs with missing pricing. The Billable spend chart on Overview and Organization > Usage show billing ledger charges, including platform fees and provider pass-through.
Settings
| Tab | Path | Purpose |
|---|---|---|
| General | /agents/:id/settings/general | Display name, platform context notes, agent ID, and app URL. |
| Source | /agents/:id/settings/source | Source provider, current ref, and GitHub export or connection. |
| Secrets | /agents/:id/secrets | Agent environment variables and connection secrets. |
| API Keys | /agents/:id/settings/api-keys | ak_ runtime keys. |
| Auth | /agents/:id/auth | Hosted app access and end-user identity. |
| Runtime | /agents/:id/runtime | Runtime machine memory. |
| Domains | /agents/:id/settings/domains | Approved embed origins and custom app hostnames. |
| System | /agents/:id/system | Runtime version, Node.js version, uptime, and repository path. |
The General display name is platform metadata. It is separate from amodal.json#name.
Source
An agent's source is either Amodal-hosted versions or a connected GitHub or GitLab repository. For a GitHub source, this tab can connect, reconnect, disconnect, or choose from the repositories granted to the Amodal GitHub App.
Export to GitHub moves Amodal-hosted source to GitHub. It requires an empty repository that the Amodal GitHub App can access. Export commits every saved version to that repository and switches the agent's source to GitHub.
Push deployment rules and deployment evals live in amodal.json, not in this tab. See CI Rules.
Secrets
Secrets are agent environment variables. Source files reference them with env:NAME. Some platform-managed secrets cannot be edited or deleted.
An admin automation token can list secret names and create, update, or delete secrets. No automation token can read a secret value.
API Keys
Agent API keys are persistent ak_ credentials for calling the deployed runtime from a server. The raw key is shown once at creation. See Authentication.
Auth
See Authentication for app access modes, runtime credentials, and identity settings.
Runtime
| Memory | Use |
|---|---|
| 512 MB | Default. Fits most agents. |
| 1 GB | Larger bundles and several connection drivers. |
| 2 GB | Heavy in-process workloads. |
| 4 GB | Maximum. Use when smaller sizes run out of memory. |
A change applies on the next deploy or runtime rollout.
Domains
| Section | Purpose |
|---|---|
| Approved Domains | Hostnames, localhost, or wildcards such as *.example.com. They do not route app traffic. |
| Custom Domains | Concrete hostnames that serve the hosted agent app. localhost and wildcards are not accepted. |
The edge does not restrict runtime calls to approved domains. It accepts cross-origin requests from any site and authenticates them by bearer token.
Custom domain status is pending, verifying, active, or error.
Embed
The Embed page configures the preview and the generated @amodalai/react/widget snippet.
| Field | Options or meaning |
|---|---|
| Enabled | Turns the widget on or off in the saved config. |
| Position | floating, right, bottom, or inline. |
| Scope | optional or required. required makes scopeId a required prop of the generated component. |
| Open by default | Opens the widget panel on load. |
| Session history | Shows previous sessions. |
| Feedback buttons | Shows thumbs up and down controls. |
| Verbose tools | Shows expanded tool details. |
| Header | Widget title text. |
| Placeholder | Input placeholder. |
| Empty state | Text shown before the first message. |
| Primary color | Accent color. |
| Mode | auto, light, or dark. |
| Allowed domains | One origin per line, saved with the config. The runtime does not enforce this list. |
A mounted widget uses its own props. Saving Embed settings does not change widgets already installed in another app. See Chat for the widget props.
Models
The Models page selects the agent's model from the catalog. It also sets an effort level for models that support one, a thinking budget, an output-token limit, and the models bound to the simple and advanced tiers. An unbound tier uses the agent's model. See Agents.
Organization-level provider credentials and model allowlists live in Organization > Model Providers.
Organization Workspace
| Page | Path | Purpose |
|---|---|---|
| Agents | /org/:orgId | List and create agents. |
| Alerts | /org/:orgId/alerts | Failure alerts across agents, such as failed runs, model and tool errors, and failed deploys. |
| Users | /org/:orgId/members | Invite users, manage roles, revoke invites, and remove members. |
| Usage | /org/:orgId/usage | Usage charges by organization and agent. |
| Billing | /org/:orgId/billing | Plan, credits, spend limit, payment methods, and subscription actions. |
| Model Providers | /org/:orgId/model-providers | Provider enablement, Amodal-managed or your own API key, base URL, verification, and allowed models. |
| Marketplace | /org/:orgId/marketplace | Publish, edit, and archive your template and plugin listings. |
| Settings | /org/:orgId/settings | Organization name, ID, plan, and creation date. |
| GitHub Access | /org/:orgId/github-access | Install the GitHub App and manage its installations. Shown to admins of company organizations. |
| Automation Tokens | /org/:orgId/automation-tokens | pk_ tokens for coding agents and CI. |
Roles are assigned per organization. Admins and developers are billable seats; viewers are free. A pending invite is billed only after acceptance. You cannot remove yourself, and the last admin cannot be demoted or removed.
Verify a model provider's credentials before sending production traffic.
Automation Tokens
Automation tokens are pk_ credentials for the Platform API. They cannot call runtime chat; exchange one for a runtime token first. See Authentication.
| Kind | Access |
|---|---|
observer | Read-only status, deploys, sessions, usage, and evals. |
operator | Observer access plus redeploy, deployment, and eval operations. No secrets, billing, or members. |
admin | Administration, including creating agents, connecting GitHub source, and managing secrets. |
A token is bound to one agent or to every agent in the organization. The UI offers 7, 30, or 90 days of validity; the API accepts expires_in_days from 1 to 365. Admin tokens default to 7 days and other kinds to 30. The raw token is shown once at creation and once after each rotation.
Every token operation requires a signed-in user session, so automation tokens cannot create, rotate, or revoke tokens. Listing, rotation, revocation, org-wide tokens, and admin tokens require organization admin permissions. An agent-bound observer or operator token requires permission to edit that agent plus the organization permissions its kind grants.
Use an org-wide admin token only for setup that creates agents or connects source. Use agent-bound operator tokens for CI deploys and observer tokens for monitoring.