Terminal and machine

Your Space is a Linux machine with ordinary files, installed tools, and Docker and Compose. Terminal opens a shell in the current workspace. Commands use the machine’s permissions and can change its files, just as commands run by Kin can once approved.

Use the shell

1. Choose the workspace and open Terminal.
2. Confirm the working folder before running commands.
3. Run your command and inspect its output and resulting files.

For a harmless first check, run pwd to print the current folder and ls to list it. A browser window is not a separate machine.

The shell belongs to the machine, not to the browser tab, so it keeps running when the tab closes or the connection drops. Rejoin shell returns to the same shell. The mouse wheel scrolls back through earlier output; dragging selects and copies text. Hold Shift while dragging to use the browser’s selection instead. A right click goes to whatever is running in the shell, so a program with its own menu gets it; hold Shift to open the browser’s menu instead.

The shell has the whole page. To talk to Kin about this workspace without leaving it, use Show the session in the top bar, the key just before Show Kin: the session floats over the terminal as a card, as it does over Files, without narrowing it. Over a terminal it stays away until you ask for it. Dock beside the page in its heading reserves a column beside the shell and resizes the terminal grid so its right-hand content stays visible. Floating it again or hiding the dock returns the room without restarting the shell. A shell watched in other windows still takes the smallest client’s size, so an explicit dock can also reflow those views. It names the workspace above the session’s title, so you can see which session you are talking to. If no session is open, the control starts one in the current workspace; a workspace Kin has not worked in before asks you to trust it first. Choosing a session while a terminal is open, in the sidebar, search, Session history or a Home card, opens it over the terminal with that session and puts the cursor in the message field, exactly as the control would; the conversation in Kin’s panel opens in the panel instead. Hide the session puts it away and gives the keyboard back to the terminal. Escape does the same while it floats, on a phone, or at the front of a stack; a docked column stays. Space remembers whether you left it open. On a phone the session covers the whole page.

Show Kin, at the end of the top bar, opens Kin’s panel instead: your default conversation with Kin rather than this workspace’s session. It floats and docks just like the session. With both open, they share a stack where they would overlap: over the shell while both float, or in the dock’s reserved column. Two docked panels stand side by side when there is room; otherwise they share the session’s reserved column.

In Terminal, Ctrl+B is the terminal’s own prefix key, not the sidebar control; Settings lists it as Give the terminal a command. On a phone or where the clipboard refuses an automatic copy, use the platform’s selection and copy controls. Physical touch and installed-browser behavior can differ from desktop Chromium.

The terminal says Connecting for a moment while it opens on your workspace. Anything you type in that moment is kept and appears once it is ready.

See every terminal at once

Terminal, near the foot of the sidebar’s rail, named Terminal, this machine, is the machine’s own view of all of them: every workspace’s shells side by side, with a mark beside each agent that is working, waiting on you, idle or done. It is the same shells the workspace terminals show, so typing in either reaches the same place.

Show the session and Show Kin work here as they do in a workspace’s terminal.

Go straight to a running agent

The Agents card, which Kin can place on your home when you ask, lists Claude Code, Codex, Kin and similar agents running in your terminals, with the ones waiting on you first. The command palette finds them too: press Ctrl+K / ⌘K and type the agent’s name, what it is working on, or its folder. Choosing one opens the terminal of the workspace it runs in; the card’s Open Terminal opens the terminal itself. If that workspace has several tabs or panes, the agent may be in another one; pick it there. An agent running outside every workspace opens this machine-wide page instead. If you are already on the terminal the agent is in, a notice names its folder and the shell takes the keyboard. Space can tell what Claude Code and Codex are doing; it shows Kin’s own terminal interface only as running.

Ctrl+B then w picks a workspace here, and Ctrl+B then b shows or hides the sidebar. A phone shows one column at a time.

Reach your terminals from another machine

Your terminals are reachable from any machine that can already reach your Space over SSH, usually through your tailnet. Nothing new is exposed to do this: it is your Space’s own SSH, and only a machine signed in as you can attach.

herdr --remote you@your-space

You see the same machine-wide view, on the same shells, and what you start there is still running when you come back to the browser.

Before it attaches, herdr may say your Space’s terminal service might not survive a lost connection and ask whether to restart it. Answer n. Yes stops everything running in your terminals, and it attaches either way.

The other machine signs in with its SSH key, which must already be on your Space; a password prompt there is not one you can answer. If herdr stops on host key verification, run ssh you@your-space once under the same name and accept the key, then try again.

Some Spaces still use the older per-workspace terminal for a workspace whose shell was already running. That workspace keeps it until you exit that shell, and the About this terminal note beside the page name says so.

Inspect the machine

Your machine, at the foot of the sidebar’s rail, answers three things in order: whether your Space is current (Updates), how much room the machine has, and how hard it is working (Activity). Its name stands beside the title, and Open Terminal beside them opens the machine-wide Terminal above.

Room shows available storage over a meter of how full the disk is, which turns to a warning colour once it is nearly full; Docker’s readiness with a count of your apps and other containers, and Open Apps; and how long the machine has been up. Refresh Your machine, in the top bar, reads the whole page again. A failed read keeps the last figures visible and labels the failure with Try again; stale figures are not a fresh measurement.

A service check that failed appears near the top, with its failure time when available. Your machine on the rail takes a mark and says Check failed or Checks failed. The service warning stays until the check recovers.

Failed temporary jobs appear separately under Previous job failures. Choose Acknowledge when you have seen a particular failure: it moves into Acknowledged failures and stops contributing to the rail’s mark. Its log stays available, and Show again returns it to attention. A later failed run needs attention again. Acknowledgment is available only when Space can identify the failed run; it does not restart work or erase the service manager’s records.

Ask Kin to look beside a failure prepares a request in the Home workspace. Review it and send when ready. For a manual check, expand Read its log yourself (or Read the logs yourself), choose Open Terminal and run the displayed command. Machine checks are incomplete means Space could not read the service manager or all the failure details; refresh to try again. A compact figure is a reading from the last successful refresh; an unavailable reading explains why it could not be checked.

Activity

Activity, last on the page, shows current resource use as four figures, with a short recent history when you ask for it. It reads your Linux machine, not the host it runs on. It makes no model call and offers no process-control actions.

• CPU is the whole machine’s non-idle time across its visible logical CPUs, with 100% meaning all of them. It includes time the VM host withheld, called steal time; it is not load.
• Memory used comes from total minus available capacity. Reclaimable cache remains available rather than being presented as memory pressure.
• Disk activity shows bytes read/written per second on device-backed disks and names the disk. Its free space is in Room, for the workspace filesystem, not an underlying host pool.
• Network shows bytes received/sent per second on device-backed NICs. Local loopback, virtual and stacked interfaces are excluded to avoid counting the same traffic again. This is transport traffic, not an app’s bandwidth.

Choose Show graphs for a graph of each over the last two minutes, with units and clock times. A gap or Unknown is not zero use: a first sample, reset, missing counter or unreadable part cannot provide a comparable rate. Stale observations are labeled with the time they were read; a failed refresh keeps the previous observations with its failure. Refresh Your machine reads Activity again with the rest of the page.

Choose Show processes to inspect the process name, PID, CPU and resident memory. Processes are read only while they are shown. Choose Name, PID, CPU or Memory to sort; choose the same heading again to reverse it. Process CPU uses one logical CPU as 100%, so a multithreaded process can exceed 100%. Unknown values sort last. Only a bounded list is shown, and an incomplete scan says so. Scroll the table on a phone, or Tab to it and use arrow keys. This is a read-only view: it shows no full command lines or environment values and offers no way to stop or change a process.

Activity refreshes about every two seconds while it is in view and the page is visible. Returning makes a fresh read. Hide processes pauses process detail reads. The short history ends when the application restarts; it is not a permanent record. Activity needs a Linux machine and is off in a disposable development home.

What persists

Event	What to expect
Leave a page or close a tab	Files and saved conversations remain; Kin and your shells keep running.
Sign out or let sign-in expire	Browser connections close. Retained files and history remain.
Restart the machine	Saved files remain, but running commands and services can be interrupted.
Push a project to GitHub	That repository’s committed work is on GitHub; this is separate from whole-machine recovery.

After interruption, inspect the command’s outcome before running it again, especially for uploads, deployments, or other external effects. A lost reply does not prove the operation failed.

Updates

When an update is ready, Your machine on the sidebar’s rail takes a mark, and its tooltip says Update ready, open or folded and in phone navigation. It does not interrupt you with a notice. The mark stays until the update is no longer waiting. Open Updates to read what is ready and whether installing it ends your sessions.

Updates leads Your machine. When nothing is waiting it is one line: the release your Space runs and when it was last checked. An update that is ready is a card above that line, with its single action and What’s changed inside it. Your Space checks for a new release once a day and again when you choose Update now…. It accepts only releases signed by Kinra: a release it cannot verify is refused, and the section says so. Checking and downloading never change what is running.

• Space 0.18.0 is up to date means the last check found nothing newer.
• Update available: Space 0.19.0 names the release. It also says whether Kin and your sessions keep running while it is installed, or whether the update replaces Kin, so your sessions end when it is installed.
• Updates are installed for you by the person who looks after your Space means the operator of your Space installs them on this machine.
• Check for updates, the refresh control beside the heading, checks now. Its icon turns while the check runs, and the line beneath explains that a new release is downloaded and verified before it is offered. Pressing it again waits for the same check. Nothing is installed by checking. It is there when your Space installs its own updates.
• The line beneath the heading or a card says Running and the release you run, when it was last checked and how the last update ended. Return to previous release… sits beside it when an earlier release is kept.
• The Machine card, when your home has one, adds an Update figure only while one is available.

Apart from these updates, a new Space installs Debian’s security fixes by itself each day and never restarts to do it; an existing Space does so once the person who looks after it turns this on.

Read release notes

Updates names the Space version you are running and the version available to install. Versions use three numbers, such as 0.1.0. Earlier releases keep their original date labels.

What’s changed shows the available update’s dated release notes, newest first. If you skipped updates, it includes the changes in those releases too. Read these before choosing Update now…; breaking changes are called out in the notes. Your running version’s notes and older entries stay under Release history, with the installed version marked. That history is kept with your installed Space and remains readable when the update channel cannot be reached.

Space verifies available release notes against the signed release. If notes cannot be reached or verified, the section says so. You can still use the update controls; checking again retries the notes as well. Older dated releases may have no recorded notes. A development build identifies itself and does not present unfinished notes as an installed release.

Install an update

1. Save any unsaved file drafts.
2. Choose Update now…. While it says Checking latest update…, Space checks for and downloads the latest signed release. This may be newer than the version the card showed, so you do not have to install each missed update in turn.
3. Read the confirmation’s version and restart warnings, then confirm. If a newer release was found, its release notes are refreshed too; choose Cancel to read them before continuing. Cancelling installs nothing.
4. Wait while the section says Updating your Space…. An activity indicator stays visible while the update starts and the page waits for the new release to respond. A brief interruption is expected while Space restarts; the page says when it is waiting for Space to respond and reloads by itself. You do not need to refresh.

The indicator shows that the page is waiting, not how much of the installation is complete. With reduced motion enabled, the animation stops and the status stays in words. If Space cannot confirm that the update finished, it leaves a warning: the work may still be running. Check the page again in a few minutes before trying another update.

If the latest check fails, nothing is installed and no sessions end. Try again once the channel can be reached or the reported problem is resolved; Space never falls back to the older cached update. If no update is waiting, the card goes away without asking you to confirm. A newly found release that would interrupt work waits until that work is settled.

Kin, your conversations and your terminals keep running through it. A reply that was still arriving continues on the page once it reconnects. Afterwards the section says The last update was installed.

Some updates say they also replace the service that holds your terminals. Those end every terminal on the machine — the ones in the browser, one opened over SSH, and one attached from another machine — along with whatever is running in them. Your Space refuses to install such an update while a terminal is running a command, and the reason beside the button says how many are. Files and saved conversations are untouched.

Update now… is unavailable, with the reason beside it, while a project is being set up or changed or while the update is still downloading. If the confirmation says an update cannot be undone automatically, it changes how your data is saved; everything else about installing it is the same.

An update that replaces Kin

Space installs Kin with the dependency versions tested for that Kin release. Newer dependency versions arrive through a later Kin release that Space adopts. If either the Kin download or its matching dependency file is missing or fails verification, installation stops. Use Updates to get the matched release.

Some updates replace Kin itself. Restarting Kin ends every live session, so your Space never installs one of these while a session is open. It ends sessions only when you choose to, or overnight where your Space’s operator allows it (see Install updates overnight). Saved history stays in Kin either way.

An update also waits while Kin is running as a terminal or background command outside the session list. Let that work finish before retrying; the update does not stop it. If the work cannot be checked, nothing is replaced.

The section lists each live session by name and says whether Kin is working in it.

1. If Kin is working in a session, or waiting on a decision from you, open that session and stop Kin or answer it. If another window or device holds a session, open it here and choose Take the keyboard, or end it there. The reason beside the button names the session.
2. Choose End my sessions and update now…. The confirmation lists the sessions that will end. With no session open the button is Update now….
3. Confirm. Your Space ends those sessions, then stops together with Kin for a few minutes while the update is installed. The page reloads by itself when they are back. Your files and your terminals stay as they are.

If a session was opened again in the meantime, nothing is installed and the section says the update was not installed because a session was still open. After an update that replaced Kin, Return to previous release… is absent: the earlier Kin is not kept, and your Space does not run an earlier release beside a Kin it never ran with.

If an update does not start properly, Space returns to the previous release when it can do so safely; otherwise it needs attention from the person who looks after your Space. Nothing you saved is rolled back. When an update was not installed at all, the section says why and that nothing was changed: another update was still running, the offered release was no longer ready, or your Space already had it. Try again shortly, or choose Check for updates first. When it asks the person who looks after your Space to look, tell them what it says.

Recovering an interrupted update may require your operator to update the machine’s update helper separately. Installing a Space release alone does not replace that helper.

Install updates overnight

Turn on Install updates overnight, below the statement in Updates, and your Space installs an update by itself once you have left it for a day. It is off until you turn it on.

Your Space installs by itself only between 3:00 and 3:45 at night, and only while nothing is in use: no page of your Space used for twenty minutes, Kin not working, and no project being set up or changed. Background agents and commands must finish too, including commands from Kin, her agents and your own ! lines. It tries once a night at most, and twice for the same update. Below the switch, Updates says what will happen to the update on offer, such as Your Space will install 0.6.1 by itself after 3:00 tonight if you’re away.

Some updates always wait for you, and Updates says so:

• one that ends your terminals;
• one that cannot be undone automatically;
• one that did not install properly before, or that you returned from;
• one that replaces Kin, unless your Space’s operator allows it. Where they do, your Space first ends your idle sessions, and only idle ones: never a session Kin is working in or waiting on you in, or one a terminal or another client holds. Their history stays in Kin.

Updates keeps the result of the overnight install, such as Your Space updated itself overnight to 0.6.1. A successful update that ended no sessions does not interrupt you. If it ended idle sessions, a notice also says how many and offers Session history… to reopen them. If your Space ended sessions for an update and then did not install it, the notice says that instead. Dismissing that notice, or opening Your machine, keeps it from returning; the result stays readable in Updates.

Return to the previous release

When an earlier release is kept, Return to previous release… restarts your Space on the release it ran before. In the Return to the previous release confirmation, choose Return to previous release to proceed, or Cancel to keep the current release. Your files, sessions and everything saved since stay as they are. The section shows activity while it waits for the previous release to respond, then reloads automatically, just as for an update. The newer release is then offered again whenever you want it. This can also be available after an operator-installed update when the update helper kept its predecessor. The control is absent when no earlier release is kept, or after an update that replaced Kin.

If Updates says Updates are installed for you by the person who looks after your Space, the daily check is not set up on that machine and nothing is wrong: its operator installs updates there.

However an update is installed, by you in another window or by your Space’s operator, a page you have open switches to the new version by itself once nothing on it would be lost. Until then it says so: save the file or note you are editing, send your message or close the dialog, and it follows. It comes back to the page you were on and the session you had open there, if that session is still live, rather than opening Home.

Network access and shared capacity

When your operator enables network isolation, your invited Space reaches services through their public addresses. Direct connections to the host’s private services and to neighboring Spaces are blocked. You still have sudo inside your own machine, and your own Docker containers can use the internet. A VPN you separately connect has its own access rules.

Small invited Spaces have a network limit of 100 Mbit/s in each direction; large invited Spaces have 250 Mbit/s. Disk reads and writes are each limited to 50 MiB/s and 2,000 operations per second for small Spaces, or 100 MiB/s and 4,000 operations per second for large Spaces. These limits reduce contention; they do not promise that much throughput at all times or reserve free disk space. A designated operator machine can have different limits.

Enabling this policy is scheduled host maintenance, separate from Update now…, and requires a restart of existing invited machines. Your operator can confirm whether it has been enabled for your Space.

Recovery and maintenance

Machine backups and restores belong to the operator of your Space. The nightly backup copies your machine as it runs and does not stop it or end your work. Other maintenance can briefly make the home unavailable and interrupt live work. Ask the operator about the current backup and recovery evidence for your machine; an installed browser app, saved chat, or kept view does not establish a verified restore.

Save browser file drafts before maintenance. If work is missing or the machine does not return, use Troubleshooting and report what you observed rather than trying destructive repair commands.