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

> ## Agent Instructions
> Install the Beam CLI, sign in, and connect coding agents to the Beam MCP server with `curl -fsSL https://www.beam.cloud/install | sh`. To also create a VM, run `curl -fsSL https://www.beam.cloud/install | sh -s -- --vm`.
> VMs are persistent Linux machines without GPUs. Defaults: 4 CPUs, 8 GiB of RAM, a 50 GiB disk, Ubuntu 24.04, and a browser desktop. A running VM accrues usage until you stop, pause, or remove it, or until an idle timeout puts it to sleep.
> Stopping a VM keeps its disk and discards RAM and processes. Pausing keeps both, and resuming restores them. To pause after 5 idle minutes and wake on access, run `beam vm update NAME --ttl 300 --idle-action pause --auto-resume`.
> Core VM commands: `beam vm new NAME`, `beam vm ssh NAME`, `beam vm sync NAME ./dir`, `beam vm exec NAME -- CMD`, `beam vm expose NAME PORT --protected`, `beam vm fork NAME NEW_NAME`, `beam vm pause NAME`, `beam vm stop NAME`, `beam vm rm NAME`.
> For GPUs, use a sandbox or a deployed endpoint. Sandboxes are disposable environments that boot in seconds and fork from snapshots.
> Current rates are at https://www.beam.cloud/pricing.

# July 27, 2023

**Released July 27, 2023**. [Link to PyPI](https://pypi.org/project/beam-sdk/0.14.0/).

# Features

### `beam run`

We are introducing a new primitive called `beam run`.

`beam run` is used to run one-off functions remotely, without having to deploy an API.

For example, let's say you wanted to run some code on Beam, but you don't want to run it in a dev session. And you don't want to deploy it as an API. You just want to run it once, remotely, on the cloud.

You can accomplish this by adding a decorator to your function. Here's what that will look like:

```python theme={null}
from beam import App, Runtime, Image, Output, Volume

app = App(
    name="vocalize",
    runtime=Runtime(
        cpu=1,
        gpu="A10G",
        image=Image(python_version="python3.8", python_packages=["torch"], commands=["apt-get install ffmpeg"]),
    ),
    volumes=[Volume(name="my_models", path="models")],
)

@app.run(outputs=[Output(path="audio_file.wav")])
def transcribe():
    return
```

You can run this code remotely on Beam by running:

```sh theme={null}
beam run my_file.py:transcribe
```

Now, `transcribe()` will be executed on Beam remotely. Logs will be streamed to your terminal, and you can also view logs, outputs, and task status in the dashboard. `beam run` also support the use of Outputs and Volumes.

# Interface Changes

### Triggers

**Triggers are now decorators on functions.** This supports the new syntax for `beam run`, and it also makes it easy to switch between Runs, REST APIs, and Task Queues very easily.

#### Old interface

```python theme={null}
import beam

app = beam.App(...)
app.Trigger.RestAPI(...)
```

#### New interface

```python theme={null}
from beam import App, Runtime

your_app = App(name="your_app", runtime=Runtime())

@your_app.rest_api()
def handler():
    return
```

### Volumes

Volumes are mounted directly to apps. This allows you to reuse app definitions across your different projects.

#### Old interface

```python theme={null}
import beam

app = beam.App(...)
app.Mount.SharedVolume(...)
```

#### New interface

```python theme={null}
from beam import App, Volume

App(
    name="my-app",
    volumes=[
        Volume(name="files", path="./files"),
        Volume(name="images", path="./images"),
    ],
)
```

### Outputs

Outputs are now added directly to triggers. We're doing this for composability and ease-of-use. It is easier to add an output directly to a trigger, instead of having a separate method outside the trigger.

#### Old interface

```python theme={null}
import beam

app = beam.App(...)
app.Output.File(...)
```

#### New interface

```python theme={null}
from beam import App, Runtime, Output

your_app = App(name="your_app", runtime=Runtime())
@your_app.task_queue(outputs=[Output(path='./test.txt')])
```

### Other Changes

* We've removed `beam.Types` from deployment triggers.
* `Outputs` will automatically infer the file type. You no longer need to specify whether the output is a `file` or a `dir`.
* You can use the `/task` API to query the status of any job running on Beam. Previously, one could only query the status of async jobs.
* `Webhook` has been renamed to `task_queue`.

> [!NOTE]
>
> We've noticed that **loaders** are not currently supported in `beam run`. This
> will be fixed in a future SDK update.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.