# Launch and manage Instances

An Instance is one running App: a desk or a service on one of your Computes. Hiring an agent launches its desk for
you ([Hire an agent](/docs/hire-an-agent)). This page launches an Instance yourself, for a service your agents use,
or a desk with no agent.

## Launch an Instance

1. Open **Instances** and press **Launch an Instance**, or press **Launch** on a service in **Apps**.
2. Under **App**, press **Choose** (or **Change**, once one is picked) to pick one from the Marketplace or your own
   Apps.
3. Give it a **Name**, and choose the **Compute** it runs on.
4. Open **Network and identity** if you need it:
   - **Network name** is how other Instances in the workspace reach it. It's filled in from the name, and fixed
     once launched.
   - **Ports** (optional, for a service) are the ones other Computes in the workspace may reach. See
     [Services and the workspace network](/docs/services).
   - **Role** (optional) is a label the audit log names it by. It's fixed once launched.
   - **Give this app its own identity** gives the Instance a key when its container starts. It then acts as you in
     this workspace and can read every variable in reach. Leave it off unless the App is built to use it.
5. Open **Environment** to give the App the values it reads, such as a database password. For each key, choose a
   saved secret, **New secret…**, **A value** for something that isn't secret, or **Not set**.
6. Press **Launch**, followed by its name.

The Instance appears in **Instances** under its Compute, **Starting**, then **Running**. Read the App's instructions
on its page for its port and how to connect.

Keep secrets out of plain values: **New secret…** saves one as a secret workspace variable, which isn't shown again
after you save it.

## Open, stop and start

- **Open** opens a desk in a new tab: see [Watch and control a desk](/docs/watch-a-desk). A service has no screen,
  so it has no **Open**.
- The **⋯** menu has **Stop**, **Start**, **Share** (a desk you own), **Details** and **Archive…**.

Stopping keeps the Instance, but anything unsaved in its apps is lost. **Start** runs it again.

## Archive

**Archive…** stops the Instance and removes it from the list for good. Anything an agent launched from it is archived
with it. Archiving loses what was on the Instance, so keep your work somewhere that lasts, such as a git remote.

## From your AI or a desk

A connected harness has `launch_instance`, `list_instances`, `start_instance`, `stop_instance`, `restart_instance` and
`archive_instance`. On a desk, `uremot instance` does the same, and `--env-file` keeps a launch's values out of a
transcript:

```sh
uremot instance list
uremot instance stop <instance-id>
```

The `uremot-apps` skill walks an AI through launching and running Instances:
[uremot-apps](/skills/uremot-apps/SKILL.md).