Coding agents
Pulsar ships no agent. Add one and it gets a briefing on this machine, health tools, and an optional sandbox that shows it one project.
Install one
The welcome window offers them at first login. Or:
$ pulsar agent list
NAME COMMAND INSTALL STATE DESCRIPTION
claude claude npm @anthropic-ai/claude-code - Claude Code (Anthropic)
codex codex npm @openai/codex - Codex CLI (OpenAI)
gemini gemini npm @google/gemini-cli - Gemini CLI (Google)
opencode opencode npm opencode-ai - opencode (open source, any provider)
aider aider uv aider-chat - aider (open source, any provider)
none is installed by default. box: agents prefix: /var/home/you/.local/share/pulsar/agents
pulsar agent add claude # then type `claude` in any terminal
pulsar agent remove claude # its command and package; your logins stay
add creates an agents toolbox, installs the agent with its vendor’s npm
or uv method into ~/.local/share/pulsar/agents, and adds a command to
~/.local/bin. No root, nothing layered. An agent you installed yourself is left in
place (listed as native) and still gets the setup below.
The toolbox is for tidiness, not safety
toolbox rm -f agents removes
it all), but shares your home folder and session. For isolation, use
the sandbox.
What it knows about the machine
/usr/share/pulsar/AGENTS.md briefs agents on this system: read-only
/usr, toolboxes, Flatpaks, what rollback covers, and what never to do.
pulsar agent guide prints it; any agent can start there.
add also links it into the agent’s own instructions if none exist (Claude Code:
~/.claude/rules/pulsar.md), links the image’s skills (including one that makes
themes), and for MCP agents registers pulsar mcp:
| Tool | What it answers |
|---|---|
doctor | the health checks, all or one |
status | deployments, pins and layered packages |
manifest | the image, the variant, the kernel and the hardware |
report | the redacted diagnosis report, with a crash if asked |
crashes | your crashes this boot |
update_check | whether a newer image is out |
agent_status | the guide, the agents, guard, the pin and the sandbox setting |
theme_list, theme_current | the desktop themes |
theme_set | the one tool that changes anything: your desktop theme, undone by pulsar theme revert |
No tool needs root, and no root command is exposed: update, rollback, checkpoint, guard and pin
stay yours. pulsar agent shows the setup:
$ pulsar agent
guide /usr/share/pulsar/AGENTS.md (pulsar agent guide)
agent claude native
sandbox off here (default) (pulsar agent sandbox)
guard off: layering and system Flatpak installs do not prompt (sudo pulsar agent guard on)
Ask it to fix something
pulsar agent default claude # the agent ask starts
pulsar agent ask # "what, if anything, looks wrong?"
pulsar agent ask why does the fan never stop # your own question
pulsar agent ask --crash latest # the newest crash, explained
pulsar agent ask --with codex # someone other than the default
ask writes a redacted pulsar report (plus the crash, if named) to a
private file in $XDG_RUNTIME_DIR (deleted at logout), then starts your agent with
a prompt pointing at it, your question, and “Do not change the system without asking me
first.” opencode: press Enter to send. aider: the report is a read-only file; paste the printed
prompt.
A crash notification’s Ask button runs pulsar agent ask --crash
in a new terminal. The report has the stack trace and logs, never the core file
(Troubleshooting). What the agent reads goes to its
provider; clicking is consent.
A model on your own GPU
opencode and aider can use a local OpenAI-compatible server, no account needed:
pulsar agent model on # the default: Qwen2.5 Coder 7B
pulsar agent model on --model <owner/repo[:quant]> --at-login
pulsar agent model # state, endpoint, key, the aider line
pulsar agent model off --purge # stop, remove, delete the downloads
-
Runs llama.cpp’s server image as a rootless user service: CUDA on the NVIDIA image, Vulkan
with a GPU at
/dev/dri, else CPU. - First start downloads the model into
~/.local/share/pulsar/models. -
Serves
http://127.0.0.1:8080/v1(local only); requests need the key in~/.config/pulsar/model-key. -
opencode: pick “Local (Pulsar)” with
/models. aider:pulsar agent modelprints the command. -
Stops at logout unless started with
--at-login(a loaded model holds gigabytes of video memory).
The sandbox
The agent runs in a rootless container that sees only the project you started it in: no SSH keys, browser profiles or other projects. Pushes go through a host-side gate that uses your credentials without exposing them and refuses force-pushes, deletions and tags.
pulsar agent sandbox on # every project, from now on
pulsar agent sandbox on --here # just this one
pulsar agent sandbox # what applies here, and why
pulsar agent sandbox push branches # never the default branch
pulsar agent sandbox push off # no pushes, no pull requests
-
The agent can commit, but git config and hooks (the repo’s, its submodules’, and any
in-project hooks path or include) are read-only, and
.gitcan’t be moved. -
A new
commondiror.gitin the tree is renamed to<name>.from-sandboxwhen the session ends. Until then, an editor running git in the background could follow it: close the editor on the project while an untrusted agent works. - Linked worktrees and submodule checkouts are refused.
Type the agent’s name as usual:
$ claude
sandboxed: only /var/home/you/code/app is visible; push on through the gate
Start it inside a project; it refuses your whole home folder. In interactive bash,
claude, codex, gemini, opencode and
aider go through the sandbox. Scripts, other shells and command claude
don’t; pulsar agent run claude always follows your settings.
pulsar agent sandbox allow ~/.local/bin/my-hook # one more path in, read-only
pulsar agent sandbox allow ~/notes --rw --here # read-write, this project only
pulsar agent sandbox repin # after you really changed a remote
pulsar agent run claude --no-sandbox # one session outside it
A repository can require the sandbox (this file can only tighten settings):
# .pulsar/agent.toml, committed to the repo
sandbox = "on"
push = "branches"
What goes in, what comes out, and what it doesn’t protect (the network): Agents and safety.
Guard, and checkpoints
On stock Fedora, an admin’s session (and anything it starts) can layer packages, roll back, and install or remove system Flatpaks without a password:
$ pulsar agent guard
guard: off
org.projectatomic.rpmostree1.install-uninstall-packages no prompt
org.projectatomic.rpmostree1.rollback no prompt
org.projectatomic.rpmostree1.cleanup no prompt
org.freedesktop.Flatpak.app-install no prompt
org.freedesktop.Flatpak.app-uninstall no prompt
sudo pulsar agent guard on makes all five ask for the admin password. Updates stay
ungated. sudo pulsar agent guard off restores Fedora’s default.
Before a long session: sudo pulsar checkpoint "before the agent"; afterwards
diff and restore. Checkpoints.
Written with help from AI and reviewed by a person before publishing. Spotted a mistake? Let us know.