> ## Documentation Index
> Fetch the complete documentation index at: https://doc.trycapsule.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# capsule service

> Manage the Capsule background service (systemd).

Capsule runs as a systemd service so it can execute scheduled backups automatically and restart after a server reboot.

## Subcommands

| Command                          | Description                                                                                                  |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `sudo capsule install-service`   | Install and enable the systemd service                                                                       |
| `sudo capsule uninstall-service` | Remove the systemd service **and delete all local Capsule data** — see the warning below before running this |

Check status and control the service directly with `systemctl`:

```bash theme={null}
# Check if the service is running
systemctl status capsule

# Start / stop / restart
sudo systemctl start capsule
sudo systemctl stop capsule
sudo systemctl restart capsule

# View live logs
journalctl -u capsule -f
```

***

## capsule install-service

```bash theme={null}
sudo capsule install-service
```

This creates `/etc/systemd/system/capsule.service`, enables it, and starts it immediately. The service:

* Runs as **root** (installing the service requires `sudo`, and the generated unit has no unprivileged `User=` override)
* Starts automatically on boot
* Restarts unconditionally, 5 seconds after it stops for any reason — not just on crashes

That unconditional restart is more than a reliability feature — it's the actual mechanism behind [auto-updates](/cli/update). When the daemon downloads a new version, it exits cleanly on purpose; systemd then relaunches it and the new binary takes over. Without this restart policy, auto-update wouldn't be able to bring the new version online by itself.

**When to run:** Immediately after `capsule auth` during initial server setup. The service is what makes scheduled backups fire — without it, schedules are configured but never executed. Install it once and forget it.

***

## capsule uninstall-service

```bash theme={null}
sudo capsule uninstall-service
```

Stops and disables the systemd unit, **and then deletes all local Capsule data** — your connections, schedules, config, and encryption key are all removed. This is not just a service-level operation; it's a full local teardown.

<Warning>
  This is destructive and cannot be undone. In particular, deleting the encryption key means any backups already uploaded from this server can no longer be decrypted by anyone — not even Capsule — unless you saved a copy first with [`capsule key show`](/cli/key). If you have existing backups you may ever need to restore, save your key **before** running this command.
</Warning>

**When to run:** Only when you're permanently decommissioning the server and have already saved your encryption key elsewhere (or no longer need the backups tied to it). This is not the right command if you just want to temporarily pause scheduled backups — for that, use `sudo systemctl stop capsule` instead, which leaves all your local data and config in place and can be reversed with `sudo systemctl start capsule`.

***

## Restrict network access (optional)

For tighter security, you can lock the service to only communicate with Capsule's API by adding network restrictions to the service file:

```ini theme={null}
# /etc/systemd/system/capsule.service
[Service]
IPAddressAllow=api.trycapsule.xyz
IPAddressDeny=any
```

After editing, reload and restart:

```bash theme={null}
sudo systemctl daemon-reload && sudo systemctl restart capsule
```

***

## Troubleshooting

**Service won't start**

Check the logs:

```bash theme={null}
journalctl -u capsule -n 50 --no-pager
```

**Scheduled backups not running**

Confirm the service is active:

```bash theme={null}
systemctl is-active capsule
```

If it's inactive, start it:

```bash theme={null}
sudo systemctl start capsule
```

**After updating Capsule**

Restart the service so the new binary takes effect:

```bash theme={null}
sudo systemctl restart capsule
```