Amodal Configuration

Amodal has two configuration scopes:

Agent workspace pages live under /agents/:agentId/* and configure one deployed agent.
Organization workspace pages live under /org/:orgId/* and configure the team, billing, model provider credentials, and shared platform access.

Visibility and editability are permission-based. Viewers may see read-only versions of pages that admins and developers can edit.

Agent Workspace

The left sidebar groups agent pages into Operate, Deploy, Resources, and Configure.

Page	Path	What It Shows
Overview	`/agents/:id`	Health summary, recent sessions, usage, model/provider status, connection gaps, and recommended actions.
Sessions	`/agents/:id/sessions`	Runtime session history, scopes, token usage, messages, tool calls, and session detail pages.
Traces	`/agents/:id/traces`	Execution traces, trace sessions, monitoring, and evaluators.
Activity	`/agents/:id/activity`	Amodal audit/activity events such as deploys, source commits, auth changes, and secret edits.
Logs	`/agents/:id/logs`	Runtime logs with filters for level, scope, session, and search text.
Cost	`/agents/:id/cost`	Cost and usage by scope, model, deploy, day, and highest-cost sessions.
Source	`/agents/:id/files`	Source browser/editor for Amodal-hosted versions or a connected Git repository. Saved source can be deployed.
Deploys	`/agents/:id/deploys`	Deploy list, deploy detail, logs, selected deploy, promote, start, stop, redeploy, and delete actions when permitted.
Evals	`/agents/:id/evals`	Eval cases and runs. Selecting several models compares their behavior on the same cases.
Connections	`/agents/:id/connections`	Connection inventory, credential status, runtime health, file completeness, endpoint details, and route probes.
Guardrails	`/agents/:id/guardrails`	Source-backed connection policy, field restrictions, and safety configuration.
Automations	`/agents/:id/automations`	Platform-managed background bindings and runs.
Stores	`/agents/:id/stores`	Store schemas and documents from the runtime store backend.
Memory	`/agents/:id/memory`	Agent memory entries when memory is enabled.
Feedback	`/agents/:id/feedback`	End-user feedback review queue.
Models	`/agents/:id/models`	Model selection, thinking/output limits, tier bindings, provider status, prices, context windows, and usage.
Prompt	`/agents/:id/prompt`	Compiled system prompt, token budget, category breakdown, and top prompt contributors.
Embed	`/agents/:id/embed`	Embeddable chat widget configuration and generated React snippet.

Sessions and Traces

Sessions lists saved conversations, ordered by Last active with the most recent first. The source filter defaults to All. Select Deployed or Local to narrow the list, or filter by scope.

Traces shows recorded runs. Traces > Sessions groups those runs by session and can include sessions without a saved conversation. These rows show Conversation unavailable; their recorded runs remain available for inspection.

Trace views default to All sources and the last 24H. Choose 7D, 30D, 90D, or All to change the time range. Summary totals on the runs and trace sessions tabs cover the entire filtered time range, while the table displays one page at a time.

Online Evaluators

Under Traces > Evaluators, online evaluators inspect 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.

The Evals page runs scenarios you author to test agent behavior. See Evals for defining and running those scenarios.

Cost and Billable Spend

Cost estimates model spend from recorded trace spans and excludes platform fees. It defaults to the last 30 days, with 7-day and 90-day views also available. Review daily trends, model and deploy breakdowns, scope usage, and the highest-cost sessions. Select a scope to filter its cost and usage; the scope comparison still shows all scopes. The page reports runs with missing pricing, so an estimate may be incomplete.

The Billable spend chart on Overview and Organization > Usage show charges recorded in the billing ledger, including platform fees and provider pass-through. Use these figures to review recorded usage charges; the trace-based Cost estimate is a separate measure.

Settings Tabs

The Settings page contains these tabs:

Tab	Path	Purpose
General	`/agents/:id/settings/general`	Agent identity and platform metadata.
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`	Agent-scoped programmatic access keys.
Auth	`/agents/:id/auth`	Hosted app protection and end-user identity.
Runtime	`/agents/:id/runtime`	Runtime machine resources.
Domains	`/agents/:id/settings/domains`	Approved embed origins and custom app hostnames.
System	`/agents/:id/system`	Runtime version, Node version, uptime, and repo path.

General

General stores platform metadata for the agent:

Field	Meaning
Name	Display name shown in Amodal lists.
Context	Optional platform-side context or notes about the agent.
Agent ID	Stable platform ID. Read-only.
App URL	Hosted agent URL when available. Read-only.
Created	Agent creation timestamp. Read-only.

This is not the same as amodal.json#name, though they should usually stay aligned.

Source

Source shows the active source provider and source ref. An agent can use Amodal-hosted versions or a connected Git repository.

Field	Meaning
Mode	`cloud` for platform-managed source; `local` for a local workspace.
Provider	`amodal` for hosted versions, `github` for GitHub, or `git` for a local Git repository.
State	`connected`, `local`, `not_configured`, or `error`.
Access	Whether Amodal can manage the connection or only read it.
Repository path	Root path used by the source backend.
Branch, ref, commit, default branch	Current selected source information.
Git status	Clean/dirty/unavailable status when the backend can report it.

When available, this tab can connect, reconnect, disconnect, or choose from GitHub repositories granted to the organization.

For Amodal-hosted source, Export to GitHub 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. Subsequent pushes trigger deployments when automatic deployment is enabled.

Automatic deployment evals are configured in amodal.json, not in this tab. They are disabled by default. For GitHub-connected agents, set ci.evals.runOn to "production" or "all" to opt in. Omitted, invalid, or unreadable configuration skips deployment evals. See Deployment triggers for the options and their scope.

Secrets

Secrets are agent environment variables. They are used for provider keys, connection credentials, OAuth tokens, JWT secrets, and other runtime values referenced by env:.

Actions:

Add a secret by name and value.
Replace an existing secret value.
Reveal a secret only when the backend allows reveal.
Delete a user-managed secret.

Some platform-managed secrets cannot be edited or deleted by users.

API Keys

Agent API keys are for programmatic access to the agent from scripts, CI, or external systems.

Actions:

Create a named key.
Copy the raw secret once at creation time.
View key prefix, creation time, and last-used time.
Revoke a key.

The secret is not shown again after creation.

Auth

See Authentication for browser login, runtime tokens, and which identity settings the hosted runtime supports.

Auth has two layers:

Deploy protection controls who can open the hosted app URL.
End-user identity configures identity verification. Its effect depends on the API or runtime host handling the request.

Deploy Protection

Maps to the hosted_auth_mode field on the platform agent record (settable via the Platform API). It is platform state, not an amodal.json field.

Mode	`hosted_auth_mode`	Behavior
Public	`public`	Anyone with the hosted app URL can open it. Runtime requests still require authentication.
Team only	`user_auth`	Only members of the agent's organization can open the hosted app. Runtime requests still require authentication.

Team-only mode uses the platform's hosted login flow. It gates app access before runtime chat begins.

End-User Identity Modes

Mode	Use When	Fields
Hosted JWKS preset	The platform host owns login and token issuance, such as the WorkOS-hosted path.	Application client ID, optional JWKS URL, optional issuer, optional audience.
Anonymous identity	No separate end-user identity provider.	Optional synthesized user ID for hosts using this strategy. The hosted runtime still authenticates platform tokens and API keys.
Shared JWT secret	Your backend already mints HMAC JWTs for users.	Shared secret, algorithm, optional issuer, optional audience.
OIDC / SSO	Configure an external OpenID Connect provider on a surface that supports OIDC.	Issuer URL, client ID, client secret, callback URL, scopes, session signing secret, optional cookie name, optional session TTL.
Trusted header	An upstream proxy authenticates users and injects identity.	Header name. Defaults to `X-Auth-User`.
Custom	You need a custom runtime `AuthStrategy`.	Module path relative to the runtime directory.

These fields describe the available configuration forms. Hosted chat installs a complete jwks verifier or uses the platform JWT verifier; saving another strategy type does not install that strategy on hosted chat. See Identity settings.

Hosted JWKS Preset

Hosted JWKS is the managed preset used when the platform owns login and organization membership. The runtime verifies hosted JWTs against a JWKS endpoint. In hosted deployments the platform can inject the JWKS URL and issuer, so the advanced fields can often stay blank.

Fields:

Application client ID: Client/application ID for the hosted login application.
JWKS URL: Remote key set used to verify hosted JWTs.
Expected issuer: Required iss claim.
Audience: Token aud; defaults to client ID when omitted.

Shared JWT Secret

Use this for Platform API end-user JWT verification or a custom runtime host using the shared-secret strategy. The hosted chat runtime does not load this strategy.

Fields:

Shared secret: HMAC secret. The Platform API verifier uses the saved value directly; it does not resolve env: references.
Algorithm: HS256, HS384, or HS512.
Expected issuer: Optional iss requirement.
Expected audience: Optional aud requirement.

OIDC / SSO

Use these fields for surfaces that support the OIDC strategy. Hosted deploy protection uses its own login flow.

Fields:

Issuer URL: IdP discovery base URL.
Client ID and client secret: Registered OIDC application credentials.
Callback URL: Redirect URI registered in the IdP.
Scopes: One per line. Defaults to openid, email, profile.
Session signing secret: Runtime cookie signing secret; keep it distinct from the IdP secret.
Cookie name: Defaults to amodal_session.
Session TTL: Defaults to 86400 seconds.

Trusted Header

Use only behind infrastructure that strips incoming spoofed headers and writes its own authenticated identity header. Do not expose trusted-header auth directly to the public internet.

Custom Auth Strategy

Custom auth loads a module from the runtime directory. The module's default export must implement the runtime AuthStrategy interface.

Runtime

Runtime settings control machine memory:

Option	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 hit OOM.

Changes take effect on the next deploy or runtime rollout. Existing machines keep their current size until then.

Domains

Domains are split into two different concepts:

Section	Purpose
Approved Domains	Browser origins allowed to embed this agent. These do not route app traffic.
Custom Domains	Hostnames that serve the hosted agent app. DNS and TLS remain on the ingress/provider unless the capability says otherwise.

Approved domains allow:

Normal hostnames, such as app.example.com.
localhost.
Wildcard hostnames, such as *.example.com.

Custom domains must be concrete hostnames. localhost and wildcard hostnames are not valid custom domains.

Custom domain status can be pending, verifying, active, or error. Depending on plan and backend capability, Amodal may allow create, delete, status refresh, and verify actions.

System

System is read-only runtime information:

Runtime version
Node.js version
Uptime
Repository path

Use these details when diagnosing runtime problems or contacting support.

Embed

Embed config controls the generated @amodalai/react/widget snippet.

Field	Options / Meaning
Enabled	Turns the widget on/off for the saved embed config.
Position	`floating`, `right`, `bottom`, or `inline`.
Scope	`optional` or `required`. Required scope adds `scopeId={tenant.id}` to the snippet.
Open by default	Opens the widget panel immediately.
Session history	Shows previous sessions in the widget.
Feedback buttons	Shows thumbs up/down feedback controls.
Verbose tools	Shows expanded tool details in the widget.
Header	Widget title text.
Placeholder	Input placeholder.
Empty state	Initial empty chat text.
Primary color	Accent color.
Mode	`auto`, `light`, or `dark`.
Allowed domains	One allowed embed origin per line. Empty means any domain.

Embed settings are stored by the platform and populate the preview and generated snippet. A mounted widget uses its props; saving Embed settings does not change widgets already installed in another app.

Models

On the Models page, select a model from the catalog and save it as the agent's model. You can set a thinking budget and output-token limit, and bind a model to the simple or advanced tier. An unbound tier uses the current model.

The page also shows:

Current model.
Available providers and credential verification.
Recent usage and priced sessions.
Model catalog with provider, model ID, input/output price, context window, usage, and status.
Filters for all, configured, and available models.

Organization-level model provider credentials and allowlists are managed from Organization > Model Providers.

Organization Workspace

Organization pages configure shared workspace behavior.

Page	Path	Purpose
Agents	`/org/:orgId`	List and create agents.
Users	`/org/:orgId/members`	Invite users, manage roles, copy invite links, revoke invites, and remove members.
Usage	`/org/:orgId/usage`	Usage charges by organization and agent.
Billing	`/org/:orgId/billing`	Plan, billing mode, credits, spend limit, payment methods, and subscription actions.
Model Providers	`/org/:orgId/model-providers`	Provider credentials, credential source, provider enablement, verification, base URLs, and model allowlists.
Settings	`/org/:orgId/settings`	Organization name, ID, plan, creation date, and GitHub App installation grants.
Automation Tokens	`/org/:orgId/automation-tokens`	Tokens for coding agents and CI.

Users

Roles are assigned at the organization level. Admins and developers are billable product seats; viewers are free. Pending invites appear in the user list but are billed only after acceptance.

You cannot remove yourself or demote or remove the last admin.

Model Providers

Each provider card supports:

Enable/disable provider.
Credential source: Amodal managed or bring your own key.
API key for BYOK providers.
Optional base URL override.
Clear saved API key on save.
Allowed model checklist.
Save and verify actions.

Verification status can be not configured, needs verify, verified, or failed. Verify credentials before sending production traffic.

Automation Tokens

Automation tokens are explicit non-browser credentials for coding agents and CI.

Access	Meaning
Observer	Read-only status, deploys, sessions, usage, and evals.
Operator	Observer plus redeploy and eval operations. No secrets, billing, or member management.
Admin	High-trust administration. Use short expirations.

Tokens can bind to all org agents or one agent. Expiration options are 7, 30, or 90 days; admin defaults to 7 days and other kinds default to 30 days. The raw token is shown once at creation.

Token creation, listing, and revocation require a signed-in user session with organization admin permissions. Automation tokens cannot create or revoke other automation tokens.

Use org-wide admin tokens only for setup flows that need to create agents or connect source repositories. After an agent exists, prefer agent-bound operator tokens for CI deploys and observer tokens for read-only monitoring.

Agent API keys under the agent settings are different: they create ak_ runtime keys for calling a deployed agent. They are not needed for platform setup, GitHub source connection, secrets, or deployments.

Billing and Usage

Usage shows recorded charges and their breakdown:

Billable tokens
Platform fee
Provider pass-through
Total usage charges
Provider spend observed
Usage by subject, including agent rows

Billing manages:

Current plan and pending plan
Billing mode: charge, invoice review, or shadow
Included credits and remaining credits
On-demand/overage usage
Spend limit
Payment methods
Plan changes and cancellation/reactivation