Documentation Index
Fetch the complete documentation index at: https://docs.terminaluse.com/llms.txt
Use this file to discover all available pages before exploring further.
This quickstart follows one path end to end:
- install the CLI
- scaffold an agent
- deploy it
- create a project and task
- pull the task output back to your machine
The point of Terminal Use is that you do not have to bolt together your own deploy flow, sandbox, task state, streaming, and filesystem transfer. You write the agent, deploy it, and get a persistent /workspace plus a task API on top.
Install and log in
uv tool install terminaluse
If tu is not found, run uv tool update-shell and restart your shell once.
Scaffold an agent
tu init creates a Python agent project with config.yaml, Dockerfile, and src/agent.py.Replace src/agent.py
from typing import Any
from terminaluse.lib import AgentServer, TaskContext
from terminaluse.types import Event, TextPart
server = AgentServer()
@server.on_create
async def handle_create(ctx: TaskContext, params: dict[str, Any]):
await ctx.state.create({"turns": 0})
await ctx.messages.send("Task created. Send me a message and I will write it to /workspace/output.txt.")
@server.on_event
async def handle_event(ctx: TaskContext, event: Event):
if not isinstance(event.content, TextPart):
await ctx.messages.send("Only text events are supported in this quickstart.")
return
state = await ctx.state.get() or {"turns": 0}
turns = int(state.get("turns", 0)) + 1
await ctx.state.update({"turns": turns})
with open("/workspace/output.txt", "a") as f:
f.write(f"turn {turns}: {event.content.text}\n")
await ctx.messages.send(f"Wrote turn {turns} to /workspace/output.txt")
@server.on_cancel
async def handle_cancel(ctx: TaskContext):
await ctx.messages.send("Task cancelled.")
Create a project
tu projects create --namespace <your-namespace> --name quickstart
Create a task and send the first message
tu tasks create \
-a <your-namespace>/<your-agent> \
-p <project-id> \
-m "hello from the quickstart"
-p auto-creates a filesystem for the task. If you already have a filesystem, use -f <filesystem-id> instead.Continue the task
tu tasks send <task-id> -m "write one more line"
Pull the task output
tu tasks pull <task-id> --out ./quickstart-output
./quickstart-output/workspace.What You Just Used
| Command | Purpose |
|---|
tu init | Scaffold an agent project |
tu deploy | Build and deploy a new version |
tu projects create | Create a permission boundary for filesystems |
tu tasks create | Start a task |
tu tasks send | Send another event to an existing task |
tu tasks pull | Download the task’s filesystem and system folders |
Next Steps
