> ## 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.

# Running Functions Remotely

> A short guide on using Beam to run one-off functions in the cloud

You can add a decorator to any Python function to run it remotely on Beam:

```python app.py theme={null}
from beam import function


@function()
def handler():
    return {"hello world"}

if __name__ == "__main__":
    handler.remote()
```

Just run this like a normal Python file, and the code will run on Beam's cloud and stream the response back to your shell.

```sh theme={null}
$ python app.py

=> Building image
=> Using cached image
=> Syncing files
=> Uploading
=> Files synced
=> Running function: <app:handler>
Loading image <d055bc4ee4ad0e61>...
Loaded image <d055bc4ee4ad0e61>, took: 3.131485ms
=> Function complete <b9ba6b86-6dfa-4bf3-89d0-75262bcc06f0>
```

> [!NOTE]
>
> By default, Beam will sync all the files in your working directory to the
> remote container. This allows you to use the files you have locally while
> developing. If you want to prevent some files from getting uploaded, you can
> create a [`.beamignore`](/v2/reference/cli#ignore-local-files).

## Passing Function Args

You can also pass arguments to your function just like normal Python functions:

```python app.py theme={null}
from beam import function

@function()
def greet(name: str):
    return f"Hello {name}"

if __name__ == "__main__":
    print(greet.remote("World"))  # "Hello World"
```

## Task Timeouts

You can set timeouts on tasks. Timeouts are set in seconds:

```python theme={null}
from beam import function


# Set a 24 hour timeout
@function(timeout=86400)
def long_timeout():
    return {"hello world"}


# Disable timeouts completely
@function(timeout=-1)
def no_timeout():
    return {"message": "hello world"}
```

## Running Tasks in the Background

By default, remote functions will stop when you close your local Python process or exit your shell.

You can override this behavior and keep the function running in the background by setting `headless=False` in
your function decorator.

```python theme={null}
import time
from beam import function


# Run the function in the background
@function(headless=True)
def handler():
    for i in range(100):
        print(i)
        time.sleep(1)

    return {"message": "This is running in the background"}


if __name__ == "__main__":
    handler.remote()
```


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