HTTP and the CLI
Use a remote server when your agent or test harness runs in another process. The same environment can be controlled through Rust, HTTP, WebSocket, stdio, the CLI, or Python.
1. Install the client
cargo install bevy_agent_cli --version 0.0.4 --locked
agentctl --versionExpected: agentctl 0.0.4. The package is bevy_agent_cli; the executable is agentctl. The crates.io package named agentctl belongs to another project.
2. Start a complete game server
Clone the repository, then leave this command running:
git clone https://github.com/briansunter/bevy-agent.git
cd bevy-agent
cargo run -p sample_platformer --example remote_http --locked -- 127.0.0.1:4000 --artifact-dir ./artifactsThe example includes the game. Installing the CLI alone does not start a server. sample_platformer is distributed through Git, not crates.io.
3. Discover, reset, and step
In a second terminal:
agentctl info
agentctl action-space
agentctl observation-space
agentctl reset --seed 42
agentctl step '{"type":"Move","x":1.0,"y":0.0}'
agentctl observeThe default endpoint is http://127.0.0.1:4000/rpc. Use --url for another server:
agentctl --url http://127.0.0.1:4001/rpc infoRead the returned observation and check terminal state before choosing the next action. Discover supported actions; movement is part of the platformer's contract.
Read the response
The CLI prints the full JSON-RPC envelope. Successful calls have a result; failed calls have an error. A successful step result includes:
| Field | Meaning | What to do with it |
|---|---|---|
tick | Completed simulation tick | Confirm the intended transition happened |
observation | The game's exposed state | Choose the next action from it |
reward | Reward for this transition | Accumulate or evaluate it in your policy |
done, truncated | Episode termination or imposed stop | Stop stepping and reset when appropriate |
checksum | Hash of declared authoritative state | Compare equivalent runs |
info | Additional environment information | Inspect game-specific diagnostics |
The control-loop guide shows an abbreviated response. agentctl observe reads the current state without advancing a tick. agentctl schema describes the available contracts.
Save, step, and restore
agentctl snapshotCopy result.snapshot_id from that response. Step once, then restore by replacing the placeholder below with that ID:
agentctl step '{"type":"Move","x":1.0,"y":0.0}'
agentctl restore <snapshot-id>
agentctl observeThe observation should describe the saved state again. For history navigation and portable files, follow Snapshots and replay. A snapshot ID belongs to the server's retained state; keep a replay bundle when you need a portable artifact.
Add a server to your own environment
Add bevy_agent_remote = "=0.0.4" to the getting-started manifest. After building your AgentApp:
use bevy_agent_remote::{HttpRemoteServer, JsonRpcBridge, RemoteSecurity};
use bevy_agent_runner::AgentApp;
fn serve(env: &mut AgentApp) -> anyhow::Result<()> {
let bridge = JsonRpcBridge::new(RemoteSecurity::default())?;
HttpRemoteServer::new("127.0.0.1:4000", bridge).serve(env)
}This library configuration disables filesystem operations. The sample explicitly enables them and confines files under its artifact root.
Call JSON-RPC directly
curl -s http://127.0.0.1:4000/rpc \
-H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"agent.info","params":{}}'The server also exposes GET /health and the WebSocket endpoint GET /ws. Always inspect the JSON-RPC body: authentication and capability failures can arrive in an HTTP 200 response.
Authentication and files
Bind to loopback for local use. Configure a nonempty session token before binding beyond loopback. The sample reads AGENT_TOKEN; the CLI reads the same variable or --token. Do not commit tokens or replay private game data without reviewing its contents.
Server-side paths resolve under the configured artifact root. A CLI --out-dir screenshots does not place screenshots next to the client process.
Continue with Python, screenshots, or retries and recovery.