133 lines
4.5 KiB
Markdown
133 lines
4.5 KiB
Markdown
# ollie
|
||
|
||
Ollie starts from a simple, slightly silly question: *What might an AI agent look like in [Plan 9](https://www.usenix.org/legacy/publications/compsystems/1995/sum_pike.pdf)?* From there follow two more: *What happens if agent primitives are exposed as an ordinary filesystem?* and *How much can we subtract from agent implementations while still being useful?* The result is not a conventional "agent framework" but a small Go runtime and 9P‑backed filesystem surface that defines what an agent is, then exposes its state and behaviors as regular files and I/O streams, so that the surrounding environment (shell scripts, TUIs, web apps, cron, containers, and other OS facilities) can handle orchestration, scheduling, workflows, and interfaces instead. Features like conductor agents, complex workflow engines, or fancy editors are optional layers you build yourself by composing ordinary file reads, writes, and processes: a tiny `s/sh` CLI, an `optimize | s/bfg` pipeline, or a Claude‑Code‑style UI talking to the same filesystem namespace.
|
||
|
||
## Getting Started
|
||
|
||
Clone with submodules:
|
||
|
||
```bash
|
||
git clone --recurse-submodules https://github.com/lneely/ollie.git
|
||
```
|
||
|
||
Or after cloning:
|
||
|
||
```bash
|
||
git submodule update --init --recursive
|
||
```
|
||
|
||
Build and install everything from the monorepo root:
|
||
|
||
```bash
|
||
mk
|
||
```
|
||
|
||
Or build specific components:
|
||
|
||
```bash
|
||
mk core # Build core library
|
||
mk 9p # Build 9p filesystem server
|
||
mk httpgw # Build HTTP gateway
|
||
mk webui # Build web UI (requires Node.js + npm)
|
||
```
|
||
|
||
For Emacs Lisp, copy `el/ellie.el` into your own Emacs configuration directory, and:
|
||
|
||
```lisp
|
||
(require 'ellie)
|
||
```
|
||
|
||
See [doc/USAGE.md](doc/USAGE.md) for usage instructions.
|
||
|
||
## Configuration
|
||
|
||
### Environment: `~/.config/ollie/env`
|
||
|
||
```
|
||
OLLIE_BACKEND=openai # ollama | openai | anthropic | copilot | kiro (default: ollama)
|
||
OLLIE_OLLAMA_URL= # base URL for Ollama (default: http://localhost:11434)
|
||
OLLIE_OPENAI_URL=https://openrouter.ai/api
|
||
OLLIE_OPENAI_KEY=sk-or-...
|
||
OLLIE_ANTHROPIC_KEY=sk-ant-...
|
||
OLLIE_COPILOT_TOKEN=...
|
||
OLLIE_KIRO_TOKEN=... # bearer token or sqlite:// path (auto-detected from Kiro CLI if unset)
|
||
OLLIE_MODEL=qwen/qwen3-235b-a22b
|
||
OLLIE_TOOLS_PATH=~/.config/ollie/tools # directory for tool scripts ({tool} steps)
|
||
OLLIE_MEMORY_PATH=~/.config/ollie/memory # directory for memory files (ollie/m)
|
||
OLLIE_ELEVATE_SOCKET=${XDG_RUNTIME_DIR}/ollie/elevate.sock # socket path for x/elevate adapter (default: $XDG_RUNTIME_DIR/ollie/elevate.sock)
|
||
```
|
||
|
||
Shell environment variables take precedence over the env file.
|
||
|
||
## Remote Access
|
||
|
||
Two approaches: mount the 9P namespace directly with `9pfuse`, or reach it over HTTP via `ollie-httpgw`.
|
||
|
||
### 9P mount
|
||
|
||
Because `olliesrv` speaks 9P over TCP, a remote instance can be mounted into the local namespace using `9pfuse`. Agent sessions, tools, and all other filesystem state on a remote host become ordinary local files — no special client needed.
|
||
|
||
```sh
|
||
# On the remote host:
|
||
olliesrv start -tcp :9564
|
||
|
||
# Locally:
|
||
olliesrv mount remotehost:9564 ~/mnt/remotehost
|
||
ls ~/mnt/remotehost # s/, t/, ...
|
||
```
|
||
|
||
Sessions created under `~/mnt/remotehost/s/` run on the remote host, so tool calls execute close to the remote filesystem rather than over the wire.
|
||
|
||
### HTTP gateway
|
||
|
||
`ollie-httpgw` translates HTTP to 9P, letting any HTTP client interact with
|
||
`olliesrv` without a 9P library. It's also the backend for the web UI.
|
||
|
||
```sh
|
||
# Connect to local server:
|
||
ollie-httpgw
|
||
|
||
# Connect to remote server:
|
||
ollie-httpgw -net tcp -addr remotehost:9564
|
||
```
|
||
|
||
See [doc/USAGE.md](doc/USAGE.md) for full details on the gateway and web UI.
|
||
|
||
### Container
|
||
|
||
A `Containerfile` is included for running a self-contained remote server:
|
||
|
||
```sh
|
||
podman build --network=host -t olliesrv .
|
||
podman run --network=host -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY olliesrv
|
||
```
|
||
|
||
Then mount locally or point httpgw at it:
|
||
|
||
```sh
|
||
olliesrv mount localhost:9564 ~/mnt/container-ollie
|
||
# or
|
||
ollie-httpgw -net tcp -addr localhost:9564
|
||
```
|
||
|
||
## Development
|
||
|
||
Update all submodules to latest:
|
||
|
||
```bash
|
||
git submodule update --remote
|
||
```
|
||
|
||
## Credits
|
||
|
||
Many sources of inspiration:
|
||
|
||
- [Plan 9 from Bell Labs](https://9fans.net) — for an interesting system
|
||
- [@9fans](https://github.com/9fans) — for the Plan 9 port
|
||
- [Suckless](https://suckless.org) — for articulating good software development principles
|
||
- [@simonfxr](https://github.com/simonfxr) — for a solid agent baseline to "borrow" from, and other nifty ideas
|
||
- [@aws](https://github.com/aws/amazon-q-developer-cli) — for a solid open-source agent implementation
|
||
|
||
## License
|
||
|
||
GPLv3 |