# Apps Overview

> Tools that do one thing well.

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

---

**Tools that do one thing well.**

Apps are the building blocks of inference shell. Each app takes structured input, does something useful, and returns structured output.

---

## The Grid

The **Grid** is our library of 100+ pre-built apps, always growing:

| Category | Examples |
|----------|----------|
| **Image** | Stable Diffusion, DALL-E, Upscaling, Background Removal |
| **Audio** | Whisper (transcription), Text-to-Speech, Music Generation |
| **Video** | Generation, Frame Interpolation, Editing |
| **Text** | Summarization, Translation, Sentiment Analysis |
| **Code** | Analysis, Generation, Documentation |
| **Data** | Processing, Conversion, Analysis |

→ [Browse the Grid](https://inference.sh/apps)

---

## Running an App

### From the Workspace

1. Find an app in the Grid
2. Click to open
3. Fill in the inputs
4. Click **Run**
5. View the results

### From the CLI

```bash
belt login        # once; for CI and headless machines set INFERENCE_API_KEY instead
belt app run namespace/my-app --input '{"prompt": "a sunset"}'
```

Use `--no-wait` to get the task ID immediately, then `belt task get <id> -f` to stream status and logs. See [Running Apps](/docs/apps/running) and [CLI setup](/docs/extend/cli-setup).

### Example: Image Generation

```
┌─────────────────────────────────────────────────────────────┐
│  stable-diffusion                                [Run ▶]    │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Prompt:                                                     │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ A serene Japanese garden with cherry blossoms       │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                              │
│  Style: [Photorealistic ▼]                                  │
│                                                              │
│  Size: [1024 x 1024 ▼]                                      │
│                                                              │
├─────────────────────────────────────────────────────────────┤
│  ● Running...                                                │
│                                                              │
│  [████████████░░░░░░░░] 60%                                 │
│  Loading model...                                            │
│  Generating image...                                         │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

Results appear when complete, with download options and task details.

---

## Using Apps as Agent Tools

When you add an app to an agent:

1. Go to your agent's settings
2. Click **Add Tool**
3. Search and select the app

The agent can now use it during conversations:

```
You: Transcribe this audio file

Agent: I'll transcribe that for you using Whisper.
       [Calling whisper with your audio file...]
       
       Here's the transcription:
       
       "Welcome to today's episode. We're going to discuss..."
```

---

## App Configuration
 
 Apps can show **setup parameters** — configuration options that determine how the app initializes (e.g. loading a specific model checkpoint).
 
 ```
 ┌────────────────────────────────┐
 │  Setup:                        │
 │  • Model: [Llama-2-7b ▼]       │
 │  • Precision: [fp16 ▼]         │
 └────────────────────────────────┘
 ```
 
 Changing these parameters restarts the app instance.
 
 ---

## Where Apps Run

Choose your infrastructure:

| Option | Description |
|--------|-------------|
| **Cloud** | Runs on inference shell managed workers. Pay-per-use. |
| **Private** | Runs on your own hardware via an Engine. |

Toggle in the app runner:

```
Run on: [● Cloud] [○ Private]
```

---

## Creating Your Own Apps

The Grid is open for extension. If you need something that doesn't exist, build it.

### Quick Start

Apps are Python scripts with typed inputs and outputs:

```python
from inferencesh import BaseApp, BaseAppInput, BaseAppOutput
from pydantic import Field

class AppInput(BaseAppInput):
    text: str = Field(description="Text to process")

class AppOutput(BaseAppOutput):
    result: str = Field(description="Processed result")

class App(BaseApp):
    async def setup(self, metadata):
        # Load models, initialize resources (runs once)
        pass
    
    async def run(self, input_data: AppInput, metadata) -> AppOutput:
        # Process each request
        return AppOutput(result=input_data.text.upper())
    
    async def unload(self):
        # Cleanup (runs on shutdown)
        pass
```

Deploy with the CLI:

```bash
belt app deploy
```

→ See [Extending Apps](/docs/extend/extending-apps) for the full guide

---

## Editing App Settings

After deploying, you can edit in the workspace:

- **Setup Parameters** — Configure initialization defaults
- **Images** — Card, thumbnail, banner for discoverability
- **Description** — Help others understand what it does
- **Visibility** — Public or private
- **Lifecycle status** — Whether the app accepts new runs (see below)

No need to redeploy for these changes.

### Lifecycle status

Lifecycle status is separate from visibility. Visibility controls who can see the app; lifecycle status controls whether it accepts new runs.

| Status | Meaning |
|--------|---------|
| `active` | Fully operational (default) |
| `maintenance` | Temporarily unavailable — new runs are rejected |
| `deprecated` | Still runs, but callers should migrate to a replacement |
| `retired` | Permanently removed from the Grid and store — new runs are rejected; task history is preserved |

Set lifecycle status in the workspace under **Visibility** on your app's detail page. Add an optional **status message** (for example, pointing users to a replacement app). Visitors see a banner on the app page when status is not `active`.

→ [Apps API — App lifecycle status](/docs/api/rest/apps#app-lifecycle-status)

---

## App Requirements

Some apps need external credentials to work:

- **Secrets** — API keys like `OPENAI_API_KEY`
- **Credentials** — OAuth connections like Google Sheets or X.com

If an app requires something you haven't set up, you'll be prompted before running.

→ [Learn about Secrets & Credentials](/docs/secrets/overview)

---

## What's Next?

- [**Flows**](/docs/flows/overview) — Chain apps into multi-step workflows
- [**Extending Apps**](/docs/extend/extending-apps) — Build and deploy your own
- [**Secrets & Credentials**](/docs/secrets/overview) — Connect external services
- [**API & SDK**](/docs/api/overview) — Run apps programmatically