Connect Walton to your VM.

The connection model

Walton does not need direct shell or SSH access to your AgentVM. The app sends a structured request to an adapter you control. That adapter translates the request into whatever your AgentVM runtime uses, waits for the result, and returns JSON to Walton.

Quick start

1. Run or create the AgentVM instance that will do the work.
2. Run a small Walton adapter beside the agent inside the VM or on a trusted gateway in front of it.
3. Expose only the adapter through HTTPS. A typical public endpoint is https://your-agent.example.com/walton/agent.
4. Require a long random bearer token and keep the AgentVM runtime itself private.
5. In Walton, open Agent, select AgentVM, select REST, paste the endpoint and token, then tap Test Connection.

The test sends a proposal-only request asking the server for a short readiness message. A successful endpoint returns HTTP 2xx with JSON containing a non-empty text field.

Walton request contract

Your adapter should accept the fields below. Some Walton surfaces send only the core fields; richer workflows can also include event context, a requested integration, an expected outcome, commerce approval state, and capability names.

{
  "mode": "plan",
  "action": "connection_test",
  "instruction": "Return a short readiness message.",
  "contextBeforeCursor": "",
  "contextAfterCursor": "",
  "executionPolicy": "proposal_only",
  "source": "ios_agent_settings_test",
  "eventContext": null,
  "requestedIntegration": null,
  "requestedOutcome": null,
  "commerceApproval": null,
  "capabilities": []
}

Minimum response

{
  "text": "AgentVM is ready."
}

Walton also accepts optional requestId and actions. Actions can describe an HTTPS destination, an integration, an approval instruction, a merchant or estimated total, or a device action such as a calendar event. Keep side effects on the server behind explicit approval, and let Walton confirm device-local work.

REST JSON

REST is the recommended transport. Walton sends the request object directly as the POST body and, when a token is configured, sends it as an Authorization bearer token.

curl -X POST 'https://your-agent.example.com/walton/agent' \
  -H 'Authorization: Bearer YOUR_LONG_RANDOM_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"mode":"plan","action":"connection_test","instruction":"Return a short readiness message.","contextBeforeCursor":"","contextAfterCursor":"","executionPolicy":"proposal_only","source":"ios_agent_settings_test"}'

Return Content-Type: application/json and a 2xx status. For errors, return an appropriate HTTP status and a short detail, message, or error string.

JSON-RPC 2.0

For RPC mode, Walton wraps the same request under params and calls the fixed method walton.execute.

{
  "jsonrpc": "2.0",
  "id": "request-id",
  "method": "walton.execute",
  "params": {
    "mode": "plan",
    "action": "connection_test",
    "instruction": "Return a short readiness message.",
    "contextBeforeCursor": "",
    "contextAfterCursor": "",
    "executionPolicy": "proposal_only",
    "source": "ios_agent_settings_test"
  }
}

Return the Walton response under JSON-RPC result. Return standard JSON-RPC errors under error.code and error.message.

WebSocket

Walton opens the configured ws:// or wss:// URL, includes bearer authorization when configured, sends one Walton request as a JSON text message, and waits for one JSON response.

What the AgentVM adapter does

The adapter is intentionally small. Walton's app-side protocol is already implemented; the server only needs to translate it into your AgentVM runtime.

1. Authenticate the bearer token before reading or executing the task.
2. Parse the JSON and validate required fields and size limits.
3. Build the AgentVM input from instruction plus any workspace context you choose to expose.
4. Honor executionPolicy. For proposal_only, disable external mutations and return a preview or plan. Only execute_approved authorizes the remote execution path.
5. Send the task to the selected AgentVM agent/session using the runtime interface available on your instance.
6. Collect the final text output, normalize it, and return {"text":"..."}.
7. Optionally translate structured results into Walton actions instead of immediately performing a device-local action.

If your AgentVM provider already gives you an HTTPS API, put this adapter at that API layer. If the VM only exposes a local runtime or CLI, run the adapter inside the VM and expose only the adapter through your reverse proxy, private tunnel, or authenticated gateway.

Production security

• Use HTTPS or WSS with a valid certificate for any internet-facing endpoint.
• Use a high-entropy bearer token and rotate it when a device or endpoint is no longer trusted.
• Do not expose SSH, a raw AgentVM control socket, or an unrestricted shell as the Walton endpoint.
• Allowlist supported actions and reject unknown modes, oversized bodies, and malformed JSON.
• Enforce proposal_only server-side; do not rely on prompt wording to prevent side effects.
• Add request timeouts, concurrency limits, rate limits, audit logs, and a kill switch for remote execution.
• Keep provider API keys and AgentVM credentials inside the VM. Walton only needs the endpoint token.

Connect it in Walton

1. Open Walton and navigate to Agent.
2. Under Agent Provider, select AgentVM.
3. Under Agent Connection, choose REST, RPC, or Socket.
4. Paste the complete endpoint URL. Walton does not append /walton/agent automatically.
5. Paste the bearer token used by your adapter.
6. Tap Save, then Test Connection.

Once saved, the same selected Agent server can power Agent chat, the command console, and the workspace terminal.

Troubleshooting

HTTP 401 or 403

Confirm the bearer token in Walton exactly matches the token expected by the gateway. Check for a proxy that strips the Authorization header.

HTTP 404

Walton uses the exact URL you enter. Include the adapter path, such as /walton/agent, in the saved endpoint.

Invalid response

Return JSON with a top-level non-empty text string. In RPC mode, put that object under result.

Works with curl but not iPhone

Check that the hostname resolves publicly or over the same private VPN used by the phone, the certificate chain is valid, and the firewall allows the phone's network path.

Request times out

Walton's interactive remote calls use finite client timeouts. For long-running work, have your adapter return a short accepted/status response and move durable jobs to a session or task model instead of holding one request open indefinitely.