bevy_agent_remote 0.0.4

JSON-RPC, HTTP, WebSocket, and stdio remote-control bridge for Bevy agent.
Documentation
# bevy_agent_remote

JSON-RPC control for Bevy agent environments over HTTP, WebSocket, and stdio.

Part of [bevy-agent](https://github.com/briansunter/bevy-agent). Requires **Bevy 0.18.1** and **Rust 1.91+**. Version **0.0.4** is experimental; pin all companion crates to the same exact version.

```toml
[dependencies]
bevy_agent_remote = "=0.0.4"
bevy_agent_runner = "=0.0.4"
```

## Serve a headless environment

```rust,no_run
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)
}
```

The server exposes `POST /rpc`, `GET /health`, and WebSocket JSON-RPC at `GET /ws`. Discovery methods expose the environment's actions, observations, schemas, and capabilities.

For a rendered Bevy app, install `BevyRemoteControlPlugin` before `app.run()`. Network I/O runs separately while world mutations and primary-window captures remain on the Bevy main thread. Enable `visual` for primary-window screenshot support; software capture works headlessly when the game supplies a renderer.

## Remote access

Bind to loopback for local use. Configure a nonempty session token before exposing the listener beyond loopback. `RemoteSecurity` controls capabilities; filesystem access is disabled by default. Enable `FILESYSTEM` explicitly and set an artifact root when you need server-side captures or replay files.

Timed-out mutations return an operation ID. Retrieve the retained result with `agent.operations.status`; use a request `retry_key` to deduplicate retries after a lost response. The retry ledger belongs to one running HTTP/WebSocket server and expires with retained outcomes; stdio does not provide it.

## Connect a client

Install `bevy_agent_cli` to get the `agentctl` executable, then use a second terminal while your server is running:

```sh
cargo install bevy_agent_cli --version 0.0.4 --locked
agentctl info
agentctl action-space
agentctl reset --seed 42
agentctl observe
```

Inspect the action catalog before sending game-specific commands. The [CLI walkthrough](https://briansunter.github.io/bevy-agent/guides/remote-control.html) includes a complete sample server and explains the JSON-RPC response. Use the [Python guide](https://briansunter.github.io/bevy-agent/guides/python.html) for a policy loop or [other transports](https://briansunter.github.io/bevy-agent/guides/transports.html) for WebSocket and stdio.

## Next steps

[Read the guide](https://briansunter.github.io/bevy-agent/guides/remote-control.html) for an organized walkthrough, examples, and troubleshooting.

- [Protocol and client guide]https://briansunter.github.io/bevy-agent/guides/remote-control.html
- [JSON-RPC operation reference]https://briansunter.github.io/bevy-agent/reference/protocol.html
- [API reference]https://docs.rs/bevy_agent_remote

Licensed under **MIT OR Apache-2.0**, at your option.