---
sidebar_position: 3
title: Manage instances
---

# Operating instances

Every lifecycle action — restart, scale, upgrade, rotate credentials, tear down — is one CLI call. All operations are scoped by **instance ID** (`a1b2c3d4`-style); `zibby app list` shows the ID alongside the display name.

## Inventory

```bash
zibby app list                            # all instances under your account
zibby app list --project <project-id>     # scope to one project
```

```
ID         Name         App         Tier    Status    Hourly    Uptime
a1b2c3d4   wiki         docmost     Heavy   running   $0.25/hr  7d 14h
a8f7e6d5   metrics      grafana     Light   running   $0.05/hr  21d 3h
b2c3d4e5   webui        open-webui  Heavy   paused    —         —
```

`paused` instances are not billed; `running` are. `status` is updated every 60s by the agent-ops sidecar.

## Single-instance status

```bash
zibby app status a1b2c3d4
```

A one-screen summary: status, resources, hourly rate, public URL, last agent-ops run.

## Logs

```bash
zibby app logs a1b2c3d4                   # last 200 lines, both containers
zibby app logs a1b2c3d4 -t                # tail mode, polls every 3s
zibby app logs a1b2c3d4 --lines 1000      # bigger window
zibby app logs a1b2c3d4 --json            # raw JSON lines
zibby app logs a1b2c3d4 --verbose         # full body, no parsing
```

Logs include both the **app** container and the **agent-ops** sidecar, prefixed by source. Tail mode reconnects automatically on network blips.

## Upgrade (zero-downtime)

```bash
zibby app upgrade a1b2c3d4
zibby app upgrade a1b2c3d4 --version 0.1.16   # pin a specific agent-ops version
```

Behind the scenes:

1. Register a new task definition revision (same image, same volume, same env)
2. Update the ECS service with the new revision
3. ALB drains old tasks while new ones come up; the listener serves the new tasks once they pass health checks
4. Old tasks shut down

A load-bearing Grafana stays serving traffic the whole time. `--yes` skips the confirmation prompt for automation.

## Restart

```bash
zibby app restart a1b2c3d4
```

Forces the ECS service to roll the current tasks — useful when an app gets wedged on a stuck connection and you don't want a full upgrade.

## Rotate credentials

For BYOK apps (e.g. open-webui pointing at Anthropic via your own key):

```bash
zibby app update-credential a1b2c3d4
```

This picks up whatever's currently in your workspace credentials (set via [Settings → Workspace credentials](https://studio.zibby.dev/settings/workspace) or `zibby creds set`) and rolls the task with the new secret env. EFS data is preserved; the task restarts in ~30s.

## ENV vars

Every app instance has a per-instance encrypted env-var bag, same shape as agent env. Use it for per-instance config (e.g. `N8N_ENCRYPTION_KEY`, `DATABASE_URL` pointing at an external RDS).

Set via the dashboard (Apps → instance → ENV tab) or via CLI:

```bash
zibby app env list a1b2c3d4
zibby app env set a1b2c3d4 N8N_HOST=automations.acme.com
zibby app env unset a1b2c3d4 OLD_FLAG
```

Changes apply on the next task restart. Use `zibby app restart` to roll immediately.

## Resource overrides

Default resources come from the catalog entry's tier. To bump CPU / memory for one instance:

```bash
zibby app deploy grafana --project <id> --cpu 1024 --memory 2048   # 1 vCPU / 2 GB
```

Per-instance overrides survive upgrades; the upgrade flow re-registers the task definition with the same override values unless `--reset-resources` is passed.

## Destroy

```bash
zibby app destroy a1b2c3d4
zibby app destroy a1b2c3d4 --yes          # skip confirmation
```

This:

1. Drains the ECS service (in-flight requests finish)
2. Deletes the service + task definition revision
3. Removes the ALB listener rule + target group
4. Releases the EFS access point — **destroys the volume data permanently**
5. Stops the billing meter immediately

There's no soft-delete. If you might want the data later, snapshot it externally first (or wait for the pause-without-destroy feature on the roadmap).

→ Next: [Agent operator](./agent-ops)