Copy page

Guides

Run your agent inside a screen

Keep an agent going with your laptop closed, as a service on the screen.

Your agent doesn't have to run on your laptop. It can run on the screen itself, as a program you start there, and keep going when you close your laptop. The agent, its model and its key are yours: Kubi doesn't install or manage one.

1. Save your model key

In the dashboard, add the key your agent needs as a secret for this screen. Secrets are in every command's environment and in /home/user/.config/kubi/secrets.env. Anything running on the screen can read them, so use a key you can revoke.

2. Install your agent

Run its install command on the screen, here with exec, or use a terminal in the live view:

Code
curl -X POST https://api.trykubi.com/v1/screens/scr_7f2kq9w3x8m4b6tzp1ac/exec \
  -H "Authorization: Bearer $KUBI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"command": "npm install -g your-agent", "timeout_s": 600}'

3. Run it as a service

A service starts again after a crash or a restart. Save this as /etc/systemd/system/my-agent.service, using sudo, which needs no password on a screen:

Code
[Unit]
Description=My agent
After=network-online.target

[Service]
User=user
WorkingDirectory=/home/user
EnvironmentFile=/home/user/.config/kubi/secrets.env
Environment=DISPLAY=:0
ExecStart=/usr/local/bin/your-agent
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Then start it, and follow its log:

Code
sudo systemctl enable --now my-agent
journalctl -u my-agent -f

DISPLAY=:0 is the desktop you see in the live view. Your agent can drive it with its own tools, or with xdotool, which every screen has.

Stepping in

Take control refuses calls to the API. An agent running on the screen doesn't need those, so it keeps using the desktop alongside you. Stop it first, and start it again when you are done:

Code
sudo systemctl stop my-agent
sudo systemctl start my-agent

Calling the API

An agent on the screen signs in like any other: create an API key bound to that screen and save it as a Kubi secret. It lands in the screen's environment with your other secrets, and every call still goes through the API.

When it needs you

Kubi doesn't carry messages between your agent and you, so give it its own way to reach you, such as a chat app or email.