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.
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`	Git-backed source browser/editor. Commits are made through Amodal and 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 suites and runs. Arena mode compares model behavior.
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 catalog, configured aliases, provider verification status, prices, context windows, and recent 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.

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`	Repository connection state and current source ref.
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 repository connection and source ref:

Field	Meaning
Mode	`cloud` for platform GitHub source; `local` for local Amodal.
Provider	Usually GitHub in cloud.
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.

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

These settings are the Amodal surface for the two auth layers. See Authentication for the full model — the browser cookie flow, API-client tokens, and how to choose a setup (and the same settings via the Platform API).

Auth has two layers:

Deploy protection controls who can open the hosted app URL.
End-user identity controls what identity the agent receives after the visitor reaches the app.

Deploy Protection

Maps to the hosted_auth_mode field (Platform API / amodal.json).

Mode	`hosted_auth_mode`	Behavior
Public	`public`	Anyone with the hosted app URL can open it. End-user identity is still controlled by the selected auth strategy.
Team only	`user_auth`	Only members of the agent's organization can open the hosted app. End-user identity is still controlled by the selected auth strategy.

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	Demo, server-to-server, or any app where per-user identity is not required.	Optional synthesized user ID. Defaults to `anonymous`. Chat/runtime calls still require runtime authentication.
Shared JWT secret	Your backend already mints HMAC JWTs for users.	Shared secret, algorithm, optional issuer, optional audience.
OIDC / SSO	You want the runtime to perform a full OAuth/OIDC login dance with Okta, Azure AD, Google Workspace, Auth0, Keycloak, etc.	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.

Use env: references for secrets such as JWT shared secrets, OIDC client secrets, and session signing secrets.

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 when your product backend mints a JWT and passes it to the widget/runtime.

Fields:

Shared secret: HMAC secret or env: reference.
Algorithm: HS256, HS384, or HS512.
Expected issuer: Optional iss requirement.
Expected audience: Optional aud requirement.

OIDC / SSO

Use this when the runtime should redirect users to an identity provider.

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 currently 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 it for support/debugging rather than agent behavior configuration.

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 in platform metadata, not committed to the agent repo.

Models

The Models page is read-only for agent-level model selection. It 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`	Billing v2 usage ledger by org 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.

Amodal prevents removing yourself and prevents demoting/removing 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. Runtime routing and final billing attribution depend on the provider gateway and cost service.

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 the source-of-truth billing ledger:

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