115 lines
4.8 KiB
Markdown
115 lines
4.8 KiB
Markdown
# ollie
|
|
|
|
An AI agent exposed as a 9P filesystem. Mount it, then use shell tools.
|
|
|
|
## Quick start
|
|
|
|
```sh
|
|
olliesrv # start the 9P server
|
|
echo "cwd=$PWD" | 9p write session/new # create a session
|
|
9p ls session/ # find the session ID
|
|
echo "hello" | 9p write session/<id>/prompt # send a prompt
|
|
9p read session/<id>/chat # read the conversation
|
|
```
|
|
|
|
## Filesystem
|
|
|
|
```
|
|
ollie/
|
|
agents available agent names (ro) 9p read agents
|
|
backends available backends (ro) 9p read backends
|
|
complete code completion (r/w) echo JSON | 9p rdwr complete
|
|
ctl server control (w) echo invalidate | 9p write ctl
|
|
generate one-shot generation (r/w) echo prompt | 9p rdwr generate
|
|
help this file (ro) 9p read help
|
|
models available models (ro) 9p read models
|
|
route task routing (r/w) echo task | 9p rdwr route
|
|
session/ sessions (dir)
|
|
idx session index (ro) 9p read session/idx
|
|
new create session (r/w) echo "cwd=/path" | 9p write session/new
|
|
<id>/
|
|
cfg session config (r/w) 9p read cfg; echo key=val | 9p write cfg
|
|
chat conversation log (ro) 9p read chat
|
|
context rendered context (ro) 9p read context
|
|
cost estimated cost (ro) 9p read cost
|
|
ctl control (w) echo stop | 9p write ctl
|
|
ctxsz context size (ro) 9p read ctxsz
|
|
env session environment (ro) 9p read env
|
|
fifo.in queue a prompt (w) echo prompt | 9p write fifo.in
|
|
fifo.out pop queued prompt (ro) 9p read fifo.out
|
|
models available models (ro) 9p read models
|
|
offset byte after last prompt (ro) 9p read offset
|
|
peer/ peer links (dir) 9p create peer/<id>; 9p rm peer/<id>
|
|
plan plan scratchpad (r/w) 9p read plan; echo text | 9p write plan
|
|
proc/ detached processes (dir) 9p ls proc/
|
|
prompt submit prompt (w) echo text | 9p write prompt
|
|
prompt.prev previous prompt (ro) 9p read prompt.prev
|
|
state agent state (ro) 9p read state
|
|
statewait blocks until change (ro) 9p read statewait
|
|
systemprompt rendered system prompt (ro) 9p read systemprompt
|
|
usage token counts (ro) 9p read usage
|
|
t/ tool scripts (dir) 9p ls t/
|
|
idx tool index (ro) 9p read t/idx
|
|
tools tool prompt lookup (r/w) echo name | 9p rdwr tools
|
|
```
|
|
|
|
## Request-response files
|
|
|
|
`complete`, `generate`, `route`, and `tools` work the same way: write a query, read the result.
|
|
|
|
```sh
|
|
echo 'file_edit' | 9p rdwr tools
|
|
echo 'implement login' | 9p rdwr route
|
|
```
|
|
|
|
## Session management
|
|
|
|
```sh
|
|
echo "cwd=/path backend=ollama model=qwen3:8b" | 9p write session/new
|
|
9p rm session/<id> # kill
|
|
echo stop | 9p write session/<id>/ctl # interrupt
|
|
```
|
|
|
|
## Switching backend/model/agent
|
|
|
|
```sh
|
|
9p read backends # list backends
|
|
9p read session/<id>/models # list models
|
|
echo backend=ollama | 9p write session/<id>/cfg
|
|
echo model=qwen3:8b | 9p write session/<id>/cfg
|
|
echo agent=myagent | 9p write session/<id>/cfg
|
|
```
|
|
|
|
Writes to cfg are rejected while the agent is running.
|
|
|
|
## Agent directory (`session/{id}/agent/{aid}/`)
|
|
|
|
Each session has at least one agent. The agent directory lives at
|
|
`session/{id}/agent/{aid}/` and contains the same files as the session
|
|
directory above (`chat`, `prompt`, `state`, `statewait`, `cfg`, `ctl`,
|
|
`offset`, `usage`, `cost`, `ctxsz`, `systemprompt`, `prompt.prev`,
|
|
`context`, `fifo.in`, `fifo.out`, `plan`, `proc/`, `t/`, `tools`).
|
|
|
|
## Environment
|
|
|
|
```
|
|
OLLIE_BACKEND ollama | openai | openrouter | anthropic | copilot | kiro
|
|
OLLIE_MODEL default model name
|
|
OLLIE_TOOLS_PATH tool scripts directory (default: ~/.config/ollie/tools)
|
|
OLLIE_SKILLS_PATH skills directory (default: ~/.config/ollie/skills)
|
|
OLLIE_MEMORY_PATH memory directory (default: ~/.config/ollie/memory)
|
|
|
|
OLLIE_OLLAMA_URL base URL for ollama (default: http://localhost:11434)
|
|
OLLIE_OPENAI_URL base URL for openai-compatible backends
|
|
OLLIE_OPENAI_KEY API key (openai, openrouter)
|
|
OLLIE_ANTHROPIC_KEY API key (anthropic)
|
|
OLLIE_COPILOT_TOKEN bearer token (copilot)
|
|
OLLIE_KIRO_TOKEN bearer token or sqlite:// path (kiro)
|
|
|
|
OLLIE_ENABLED_BACKENDS backends available for routing (comma-separated)
|
|
OLLIE_ROUTE_BACKEND backend for /route classifier (default: ollama)
|
|
OLLIE_ROUTE_MODEL model for /route classifier (default: qwen3:8b)
|
|
```
|
|
|
|
Set defaults in `~/.config/ollie/env` (KEY=VALUE, one per line).
|