Skip to main content
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 TerminalUse 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.
1

Install and log in

uv tool install terminaluse
If tu is not found, run uv tool update-shell and restart your shell once.
tu login
2

Scaffold an agent

tu init
tu init creates a Python agent project with config.yaml, Dockerfile, and src/agent.py.
3

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.")
4

Deploy the agent

tu deploy -y
5

Create a project

tu projects create --namespace <your-namespace> --name quickstart
Copy the returned project ID.
6

Create a task and send the first message

tu tasks create \
  -a <your-namespace>/<your-agent> \
  -p <project-id> \
  -m "hello from the quickstart"
Using -p auto-creates a filesystem for the task. If you already have a filesystem, use -f <filesystem-id> instead.
7

Continue the task

tu tasks send <task-id> -m "write one more line"
8

Pull the task output

tu tasks pull <task-id> --out ./quickstart-output
Your task filesystem will be under ./quickstart-output/workspace.

​
What You Just Used

CommandPurpose
tu initScaffold an agent project
tu deployBuild and deploy a new version
tu projects createCreate a permission boundary for filesystems
tu tasks createStart a task
tu tasks sendSend another event to an existing task
tu tasks pullDownload the task’s filesystem and system folders

​
Next Steps