Your first session

A session is one conversation with the agent, stored on disk so you can come back to it.

#Open it

Go to your project and start orrery:

cd ~/code/my-project
orrery

It always opens and always shows a banner first: the version, the workspace (and whether it is trusted), and the model in use. Then:

• Nothing set up yet: it opens /providers. Pick a provider, answer its steps, pick a model. The setup is saved to ~/.orrery/config.toml.
• Providers set up, none in use: it opens /model.
• A model in use: you are at the prompt.

#Trust the workspace

The banner says whether the workspace is trusted. An untrusted workspace does not load its own configuration (.orrery/config.toml), extensions or agents. Your user settings still apply.

If this is your own project, trust it:

orrery trust grant .

See Workspace trust.

#Talk to it

Type a request and press Enter. While the turn runs, the line under it says what the agent is doing: thinking · 3s, running shell · 5s, needs approval.

• Every tool call is one folded line, such as ● read src/lib.rs. Press ctrl+o to open the last one.
• Type while a turn runs and press Enter to steer it. The line lands in the agent's next step.
• Press Esc to stop the turn.

#Answer a permission prompt

When the agent wants to do something a rule says to ask about, a consent bar appears above the input. Press y to allow once, a to allow always, n to deny, d to deny always. See Permissions and consent.

#Leave and come back

Press ctrl+d to quit. Orrery prints a summary with the exact command to resume:

orrery · default · session ended
  duration  4m 12s
  cost      $0.0831 · 41.2k tokens
  turns     6
  resume    orrery --resume 01a0df68-2f95-7863-9f0e-034c2be5dde0

orrery --continue reopens the latest session in this workspace. See Sessions and resume.

#Next

• The TUI and its keys
• config.toml and layers