# Running an App

> How to run an app from the workspace.

**URL:** https://inference.sh/docs/apps/running
**Last updated:** 2026-10-12

---

How to run an app from the workspace.

---

## Open the app

Find it in the Grid and click to open.

Multi-function apps show a **function** selector in the runner. The URL stays in sync with your choice (`?function=<name>`), so you can bookmark or share a specific entry point. See [Browsing the Grid — Multi-function apps and shareable links](/docs/apps/browsing-grid#multi-function-apps-and-shareable-links).

---

## Fill in inputs

Each app has a form with required and optional fields:

```
stable-diffusion

Prompt: [________________________]  ← required

Style: [Photorealistic ▼]           ← optional

Size: [1024 x 1024 ▼]               ← optional
```

---

## Choose where to run

| Option | Description |
|--------|-------------|
| **Cloud** | Runs on inference shell workers |
| **Private** | Runs on your own hardware |

Toggle at the top of the runner.

---

## Click Run

The task starts. You'll see:

- **Status** — Queued → Running → Complete
- **Progress** — Percentage and logs
- **Results** — Outputs when done

---

## Download results

Files (images, audio, etc.) have download buttons.

Click to save to your computer.

When the app publisher configured a **ui page** on the active version (an [artifact](/docs/artifacts) rendered instead of the generic output), the runner shows that page above or beside the structured results. The same page appears in chat when an agent runs the app. Publishers set it in the app editor under **requirements → ui page**; see [Apps API — Custom UI page](/docs/api/rest/apps#custom-ui-page-ui).

---

## View in Tasks

All runs appear in [Tasks](https://app.inference.sh/tasks).

Go there to see history or re-download results.

---

## From the CLI

Run the same app from your terminal (after [CLI setup](/docs/extend/cli-setup)). Sign in once with `belt login`, or set `INFERENCE_API_KEY` on CI and headless machines:

```bash
belt login
belt app run namespace/my-app --input '{"prompt": "a sunset"}'
belt app run namespace/my-app --input input.json
belt app run namespace/my-app '{"prompt": "a sunset"}'       # positional JSON
echo '{"prompt": "a sunset"}' | belt app run namespace/my-app  # piped stdin
belt app run namespace/my-app -i '{"prompt": "a sunset"}' --jq '.output.url'  # filter output
```

By default the CLI waits until the task completes and prints the output. For long-running jobs, return immediately and follow progress separately:

```bash
belt app run namespace/my-app@version --input input.json --no-wait
belt task get <task-id> -f      # status, logs, and output until complete
belt task logs <task-id> -f     # logs only (filter with --type run, setup, etc.)
```

Input resolves from `--input`, a positional argument, or piped stdin (in that order). Each accepts inline JSON, `@filename`, or a JSON file path. See [CLI setup — JSON input](/docs/extend/cli-setup#running-apps) and [Tasks](/docs/concepts/tasks) for status codes, cancellation, and webhooks.

When output includes file URLs (images, audio, video), download them with `belt file download <url>` — see [CLI setup — Files](/docs/extend/cli-setup#files-cli).

→ [CLI setup](/docs/extend/cli-setup) · [Tasks API](/docs/api/rest/tasks)

---

## Cancel a run

While status is **Running**, click **Cancel** in the runner or on the task detail page. The platform requests a graceful stop; see [Tasks](/docs/concepts/tasks#cancelling) for API, CLI (`belt task cancel`), and MCP cancellation.

---

## Next

→ [Setup Parameters](/docs/apps/setup-parameters)