Connect Walton to your VM.

The connection model

Provisioning and runtime access are separate. AgentVM creates and operates the cloud VM from a server, workstation, CI job, or other trusted provisioning environment. Walton for iOS is only a remote client: it connects to an endpoint on an AgentVM instance that already exists.

Provision AgentVM separately

Provision and operate AgentVM from a trusted environment that is allowed to create cloud infrastructure. That can be a workstation, server, CI system, or provisioning backend. Do not embed cloud-provider credentials or AgentVM provisioning credentials in the Walton iOS app.

1. From your workstation, server, CI system, or provisioning backend, use AgentVM to create the VM with the provider and operating system you want.
2. Install or start the agent workload inside that VM.
3. Run a small Walton-facing HTTP/WebSocket service inside the VM, or put a trusted gateway in front of the VM.
4. Give that service a stable HTTPS or WSS address and its own bearer token.
5. Give the user only the runtime endpoint and token needed by Walton. Keep provider credentials and VM lifecycle privileges out of the phone.

The provisioning and provider control plane stays separate from Walton. The iOS app only needs the narrow runtime endpoint used to submit agent work and receive results.

Quick start after the VM exists

1. Provision the AgentVM instance outside Walton.
2. Run a small Walton adapter beside the agent inside the VM or on a trusted gateway in front of it.
3. Expose only that adapter through HTTPS. A typical endpoint is https://your-agent.example.com/walton/agent.
4. Require a long random bearer token and keep AgentVM lifecycle APIs, provider credentials, SSH, and raw shell access private.
5. In Walton, open Agent, select AgentVM, select REST, paste the already-provisioned 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. It is a runtime bridge, not a VM provisioner. Walton's app-side protocol is already implemented; the server only needs to translate it into the agent/runtime interface available on the AgentVM instance.

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.

Run the adapter after provisioning, preferably inside the AgentVM instance or on a trusted gateway that can reach it. Do not expose the AgentVM provisioning/control plane directly to Walton. The phone should receive only the narrow runtime endpoint required to submit agent work and receive results.

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 cloud-provider keys and AgentVM provisioning credentials off the phone. Walton only needs the runtime 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.