Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Source & Deploy In Amodal

This guide walks through the Amodal path: connect a GitHub repo, create an agent, deploy it, promote production, and inspect the result. Use it after you understand the project structure or after you build the support-agent tutorial.

1. Connect GitHub

Open Amodal, choose your organization, and connect GitHub from the agent creation flow.

The GitHub installation controls which repositories Amodal can see. If a repo does not appear, check the GitHub App installation and make sure the repo is selected there.

2. Create an Agent

Create a new agent from an existing repo. An agent repo contains plain files:

amodal.json
amodal/
├── connections/
├── skills/
├── knowledge/
├── stores/
├── tools/
└── intents/
hooks/
evals/
src/                    # optional custom runtime app

amodal.json is the manifest. The reserved folders under amodal/ define what the agent knows, what it can call, what data it stores, and which typed actions it can run. hooks/ defines guardrails and evals/ defines quality checks. A repo can also include a normal frontend app when it enables runtimeApp.custom.

3. Configure Models, Secrets, and Access

In Amodal, open the agent settings and configure:

  • Models — choose the agent's current model from the Amodal Models page. If you do not choose one, the platform default is Gemini 2.5 Flash.
  • Model providers — configure organization-level provider credentials and model allowlists from Organization settings.
  • Secrets — connection credentials, OAuth tokens, JWT secrets, and other runtime values referenced with env:.
  • Auth, embed, and domains — control who can open the deployed agent and where the widget can be embedded.
  • Runtime and deploy settings — memory, runtime state, source connection, deploys, and production promotion.

Model selection is operational platform state, not amodal.json source. Secrets also stay in the platform/deployment environment. Source files should reference secrets by name, not contain secret values.

4. Deploy

Open Source in Amodal, inspect the repo, then deploy the current commit.

Amodal separates source history from deploy history:

  • Source shows commits, branches, files, and diffs.
  • Deploys shows materialized deployments, runtime state, URLs, and which deploy is production.
  • Promote points the production URL at a selected deploy.

For a new agent, the first deploy creates the runtime. Before that, runtime-backed pages such as Sessions, Cost, Logs, and Prompt may have no data to show.

5. Chat and Inspect

After deployment, open the deployed agent URL from Amodal or the Deploys page. Ask a question that exercises a connection:

What happened in the incidents channel today?

Amodal records the session so you can inspect:

  • Messages and tool calls
  • Scope and session IDs
  • Model and token usage
  • Runtime logs
  • Activity and deployment context

If chat is slow, check the session's actual model and tool-call timing before changing source. Slow turns usually come from a configured non-default model, provider retries, or a connection/tool call, not from the SPA itself.

6. Edit and Redeploy

Open Source, edit a skill, knowledge file, connection doc, store schema, intent, eval, or custom runtime app, then review the diff.

When you commit, Amodal asks for:

  • Branch
  • Commit message
  • Promotion behavior

After the deploy finishes, the Deploys page shows the new runtime state and whether production points at it.

7. Add Evals

Add Markdown evals in evals/ and run them from Amodal. Evals let you compare behavior across models and catch regressions before promoting a deploy.

Next Steps