Coding Agents

Coding agents are private terminal workspaces for AI coding tools such as Codex, Claude Code, Gemini CLI, OpenCode, and generic command-line assistants.

They are not public services. A coding agent has no public app URL, is opened from the Moltern dashboard, and receives access only to the applications, services, and databases you explicitly select.

How Coding Agents Work​

The workflow has five parts:

1. Create an agent in a specific environment.
2. Choose the provider CLI you want to use.
3. Sign in to that provider from the terminal and save the completed sign-in, or use a supported provider key.
4. Grant the agent read or connection access to selected apps and services.
5. Open the terminal and run the agent against the generated workspace context.

The agent runtime includes bash, git, common shell utilities, and provider CLIs for claude, codex, gemini, and opencode when the current runtime image includes them.

Use coding agents when you want to:

• run an AI coding assistant close to your Moltern workloads
• inspect app and service context without copying credentials to your laptop
• grant temporary access to one service or database, then remove it later
• keep commands and generated files inside a private terminal workspace, with saved provider access restored when the agent starts
• use multiple terminal tabs for parallel work such as app changes, database checks, and tests

Choose A Provider​

Choose the provider based on the CLI your team already uses. The permission model is the same for every provider.

If the selected command is not available in the runtime, Moltern shows a clear message and opens bash in the same workspace so you can continue manually.

Create An Agent​

1. Open Coding Agents from the Moltern sidebar.
2. Enter a clear name, such as Codex workspace or Docs migration assistant.
3. Choose the environment where the agent should run.
4. Choose the provider.
5. Decide whether to keep workspace files between restarts.
6. If persistence is enabled, choose the workspace storage size.
7. Review Agent slot preview. It shows the workspace plan, current workload count, and whether creation is allowed.
8. Select Create terminal agent.

After creation, Moltern opens the agent detail page.

Creating an agent uses one workspace workload slot. It does not reserve runtime CPU or RAM until you start the terminal runtime.

Persistent Workspace​

Use a persistent workspace when the agent needs to keep files, package installs, generated patches, shell history, or provider configuration between restarts.

Use an ephemeral workspace when the agent is only needed for a short task and you do not want files to remain after restart or deletion.

New agents start with a persistent workspace selected. Clear that option during creation when the task should use an ephemeral workspace instead.

Persistent workspace storage uses the same workspace storage pool shown in Billing. Moltern measures the agent workspace files as part of normal workspace usage.

Delete unused persistent agents after the task is complete. This releases the runtime and schedules the agent workspace data for cleanup.

Configure Provider Access​

The Overview tab shows runtime details and provider sign-in options.

Use A Provider Account Or Subscription​

Codex, Claude Code, Gemini CLI, and OpenCode expose their supported account flow in Provider access. The exact browser, device-code, or provider-selection step is controlled by that provider.

1. Select Open sign-in terminal. Moltern starts the runtime when needed and opens Terminal 1.
2. Complete the provider's sign-in flow in Terminal 1. Follow any browser or device-code instructions shown by the provider CLI.
3. Return to Overview.
4. Select Save completed sign-in.
5. Confirm the provider status changes to Saved.

Saving the completed sign-in lets Moltern restore that provider session when the agent runtime is replaced or restarted. Saved means Moltern has a restorable copy of the completed sign-in; it does not extend the provider's session lifetime. If the provider expires or revokes the session, sign in again and save the updated session. The provider's tokens are never returned by the Moltern API or shown again in the UI.

To switch accounts or refresh an expired session, repeat the provider sign-in in Terminal 1 and select Save updated sign-in. The new session replaces the previously saved session.

Saving or replacing provider access requires a recent account confirmation. Enter your current Moltern password, or confirm with the Google or GitHub identity already linked to your account. A successful confirmation remains available for sensitive agent actions for 15 minutes in the current browser tab.

Use A Key Or Token​

Some workflows use API keys instead. In that case:

1. Open the Overview tab.
2. Paste a supported provider key or token into its field.
3. Select Save key securely.
4. Open a new terminal session if the agent was already running.

Saved provider credentials are write-only from the UI. Moltern does not show them again after saving. To rotate a value, paste the replacement and select Replace saved key.

Disconnect Provider Access​

Select Disconnect provider to remove the saved account session, key, or token. Moltern ends active terminal sessions and replaces the private runtime so the disconnected provider access is no longer available to running processes. The agent, workspace files, and resource permissions remain available.

You can reconnect later from the same Provider access card.

Grant Access To Apps And Services​

Open the Permissions tab to decide what the agent can see or connect to.

Each target can be an application, service, or database service. Each selected target has a scope.

No grant means the agent receives no private context or connection data for that target.

Runtime Connect Vs Read Context Only​

The label beside each target tells you what Moltern can safely prepare.

• Runtime connect means the target can receive runtime variables. For an application this can include a URL variable. For a managed service or database this can include connection variable names.
• Read context only means the agent can see the target in AGENTS.md, but Moltern will not add runtime connection variables for it.

If Connect is disabled for a target, choose Read context unless you first change the target so it exposes safe connection details.

Runtime Aliases​

Each grant has an alias. The alias becomes the prefix for variables in the terminal.

Example:

Use short, clear aliases. Avoid generic names like DB when the agent can access more than one target.

Save And Restart​

After changing permissions:

1. Select Save permissions.
2. Confirm your account when prompted.
3. Restart the agent if it is already running.
4. Open AGENTS.md or the terminal to confirm the updated policy.

Moltern refreshes the generated access block when the runtime starts. If a running terminal still shows old access, restart the agent.

Understand AGENTS.md​

/workspace/AGENTS.md is the main instruction file for the agent.

The file has two important parts:

• A generated access block managed by Moltern.
• Your editable workspace notes below or around that block.

The generated block lists:

• agent name and provider
• whether the terminal and internet access are enabled
• allowed applications
• allowed services and databases
• runtime variable names
• restrictions the agent should follow

The generated block lists variable names only. Sensitive values are provided to the runtime separately and are not printed in the docs page, AGENTS.md, or the UI preview.

Provider-specific instruction files are also prepared:

• CLAUDE.md points Claude Code at the same instructions.
• GEMINI.md points Gemini CLI at the same instructions.
• Codex and OpenCode can read AGENTS.md directly from the workspace.

You and the agent can edit AGENTS.md. Moltern refreshes only the generated policy block when permissions change, then keeps your notes.

Open The Terminal​

Open the Terminal tab after the agent is running.

The terminal supports:

• automatic provider CLI launch
• bash fallback when the provider command is unavailable
• terminal search
• visible scrollbar
• browser scrollback
• shell command history for the runtime session
• multiple terminal tabs backed by reusable sessions

Moltern starts the selected provider command when available:

codex      # Codex agent
claude     # Claude Code agent
gemini     # Gemini CLI agent
opencode   # OpenCode agent

Useful first checks:

pwd
cat /workspace/AGENTS.md
which codex claude gemini opencode
env | sort

Do not print secrets in shared logs, screenshots, issues, pull requests, or documentation.

Multiple Terminal Tabs​

Use multiple tabs when you want separate sessions for different tasks:

• one tab for the provider CLI
• one tab for package install or test commands
• one tab for checking an application or database connection

Closing a tab ends that terminal session. Reopening the same tab reconnects to the existing session when it is still available.

Work With Connected Services​

After you grant Connect access, the terminal can use the generated variables.

Example pattern for an application URL:

echo "$STOREFRONT_URL"
curl -I "$STOREFRONT_URL"

Example pattern for a database service:

echo "$ORDERS_DB_HOST"
echo "$ORDERS_DB_DATABASE"

Use the client or framework that matches your service. If a database client is not installed in the agent runtime, install it in the workspace or use a development service designed for that database workflow.

Update Settings Or Delete An Agent​

The Settings tab controls the agent workspace.

You can:

• rename the agent
• enable or disable persistent workspace files
• change workspace storage size
• delete the agent and workspace

Delete unused agents when a task is complete. Deletion removes the agent runtime, terminal sessions, saved grants, and persistent workspace storage when it was enabled.

Moltern asks you to confirm your account before deleting an agent or turning off persistent workspace storage. These actions can remove saved access or workspace data. Renaming an agent and increasing its workspace size do not require another confirmation.

Security Checklist​

Before starting an agent:

• Grant only the apps and services needed for the task.
• Prefer Read context when the agent only needs architecture context.
• Use Connect only when the terminal must call or connect to the target.
• Use Admin hint only for setup or repair work.
• Keep aliases specific enough to avoid mistakes.
• Restart the agent after permission changes.
• Disconnect provider access when the agent no longer needs to call the provider.
• Revoke grants or delete the agent when the task is complete.

Coding agents should be treated like active developer workspaces. They can run commands and use any runtime variables you grant to them.

Billing And Resource Notes​

Running agents and persistent workspaces consume workspace resources.

Before Start terminal or Restart terminal, the Overview tab shows the projected runtime impact. The preview includes the agent's CPU, RAM, and runtime-instance reservation alongside the workspace total. Moltern checks this before changing an existing runtime, so a quota-blocked restart leaves the current runtime untouched.

When the preview is blocked, open Billing from the preview. A paid workspace can use eligible pay-as-you-go overages only when PAYG is enabled and the projected amount stays within its monthly cap. Terminal tabs are sessions inside one agent runtime and are not billed as separate workloads.

To control usage:

• stop agents when they are not being used
• delete short-lived agents after the task is done
• use ephemeral workspace mode for quick tasks
• keep persistent workspace storage sized to the actual task
• review Billing after deleting an agent with persistent workspace files

Troubleshooting​

Terminal Is Unavailable​

Start or restart the agent and wait for the runtime to become ready. If it still fails, refresh the page and open a new terminal session.

Provider CLI Does Not Start​

If the terminal says the selected CLI is not installed, restart the agent after the latest runtime image is deployed. Moltern opens bash so you can continue manually.

Provider Login Does Not Work​

Use Open sign-in terminal so the flow runs in Terminal 1. Check whether the provider expects browser login, device-code login, subscription login, provider selection, or an API key. After the provider confirms sign-in, return to Overview and select Save completed sign-in.

If Moltern says no completed sign-in was found, keep the runtime running, finish the provider flow in Terminal 1, and retry the save action. For a key replacement, open a new terminal session after saving.

Account Confirmation Does Not Open​

Allow pop-ups for Moltern when confirming with Google or GitHub. The confirmation must use the identity already linked to your Moltern account. Password accounts can enter their current account password directly in the confirmation dialog.

If a confirmation has expired, repeat the action and confirm again. Moltern does not keep the short-lived confirmation after you sign out, reload the application, or close the tab.

A Service Is Missing From AGENTS.md​

Open Permissions, select the service, choose the right scope, save permissions, and restart the agent.

Connect Is Disabled For A Target​

Use Read context for that target. Connect is available only when Moltern can prepare safe runtime variables for the target.

A Revoked Service Still Appears In The Terminal​

Save permissions again, restart the agent, then inspect /workspace/AGENTS.md.

The Agent Cannot Reach A Package Registry Or Provider API​

Confirm the agent is running and that the provider command is using the expected login or API key. Some provider CLIs also need you to finish an interactive login flow before they can call their API.

Related Guides​

• Applications
• Services And Databases
• Private Service Connections
• Environment Variables And Secrets
• Development Service Terminal
• Billing And Usage