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

# Core Concepts

## How Beam Works

Beam packages your code into a container and runs it on compute in the cloud.

Beam's runtime is powered by the [open-source Beta9 orchestrator](https://github.com/beam-cloud/beta9).

```mermaid theme={null}
flowchart LR
    localCode["Your Python code + decorator"] --> beam["Beam"]
    beam --> container["Container in the cloud"]
    container --> autoscale["Scales within configured limits"]
    container --> shutdown["Can scale to zero"]
```

Serverless containers scale within your autoscaler settings and workspace limits. Reserved machines and always-on configurations have different lifecycles; see [pricing](/v2/resources/pricing-and-billing).

<Note>
  The examples below use the [Python SDK](/v2/reference/py-sdk), which provides Beam's decorator programming model. The [TypeScript SDK](/v2/reference/ts-sdk) offers programmatic access for creating sandboxes and calling deployed endpoints.
</Note>

## Sandboxes

A sandbox is a computer for an agent: a container you drive from code to start processes, read and write files, expose ports, and snapshot its filesystem or memory to fork it. Use sandboxes to give agents a machine to work in, and for development environments and RL rollouts. [Learn more about Sandboxes](/v2/sandbox/overview).

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

sb = Sandbox(cpu=1, memory="1Gi").create()
print(sb.process.run_code("print('hello')").stdout)

snapshot_id = sb.snapshot_memory()  # fork it later with create_from_memory_snapshot()
sb.terminate()
```

Unlike endpoints and task queues, a sandbox isn't deployed. Your code creates it at runtime and terminates it when it's done, or the sandbox's TTL expires.

## Functions

You can run functions on the cloud, either once, or on a schedule. [Learn more about Functions](/v2/function/running-functions).

<CardGroup cols={2}>
  <Card title="Functions" icon="code">
    One-off Python functions, like training runs, scraping, or batch jobs.

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

    @function()
    def handler():
        return {}

    if __name__ == "__main__":
        # Runs locally
        handler.local()
        # Runs on the cloud
        handler.remote()
    ```
  </Card>

  <Card title="Scheduled Jobs" icon="clock">
    Functions that run based on a schedule you specify.

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

    @schedule(when="0 0 * * *")
    def handler():
        return {}

    if __name__ == "__main__":
        # Runs locally
        handler.local()
        # Runs on the cloud
        handler.remote()
    ```
  </Card>
</CardGroup>

<CardGroup cols={1}>
  <Card title="Run Your Function" icon="bolt">
    You'll run your functions like a normal Python function: `python app.py`.
    Even though it *feels* like the code is running locally, it's running on a
    container in the cloud.
  </Card>
</CardGroup>

## Endpoints

You can also deploy synchronous and asynchronous web endpoints. Learn more about [Endpoints](/v2/endpoint/overview) and [Task Queues](/v2/task-queue/running-tasks). To call a model without deploying one, use [hosted models](/v2/endpoint/hosted-models).

<CardGroup cols={2}>
  <Card title="Endpoints" icon="bolt">
    Synchronous REST API endpoints with a configurable request timeout.

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

    @endpoint(name="quickstart")
    def handler():
      return {}
    ```
  </Card>

  <Card title="Task Queues" icon="layer-group">
    Asynchronous REST API endpoints, for heavier tasks that take a long time to run.

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

    @task_queue(name="quickstart")
    def handler():
      print(48393 * 39383)
    ```
  </Card>
</CardGroup>

<CardGroup cols={1}>
  <Card title="Testing Your Code (Optional)" icon="loader">
    Beam provides a temporary cloud environment to test your code.

    <br />

    These environments hot-reload with your code changes. You can test your workflow end-to-end before deploying to production.

    ```bash theme={null}
    beam serve app.py:handler
    ```
  </Card>
</CardGroup>

<CardGroup cols={1}>
  <Card title="Deploying to Production" icon="check-double">
    When you're ready to deploy a persistent endpoint, you'll use `beam deploy`:

    ```bash theme={null}
    beam deploy app.py:handler
    ```
  </Card>
</CardGroup>

A schedule starts recurring execution after you deploy it with `beam deploy app.py:handler`; calling `.remote()` runs one invocation. Cron schedules use UTC.

## Apps, deployments, and containers

An **app** groups related versions. A **deployment** is a version of a workload's code and configuration. A **container** is a running instance of that version; an active deployment can have zero containers while idle. A **task** records an invocation. A **stub ID** identifies a workload configuration and is distinct from the deployment and container IDs.

[Stacks](/v2/hosting/stacks) group apps. [References](/v2/hosting/references) connect their environment variables to database credentials, secrets, or another app's URL. [Databases](/v2/data/databases) run as stateful services with durable disks.

## Web Services

You can also bring your own container and host web services, like Jupyter Notebooks, Node.js apps, and much more. [Learn more about Pods](/v2/pod/web-service).

<Card title="Pods" icon="bolt">
  Run a container with HTTP or TCP ingress, or without ports for background work. For Dockerfiles and registry images, start with the [container guide](/v2/hosting/containers).

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

  pod = Pod(
    name="my-pod",
    cpu=2,
    memory="1Gi",
    ports=[8000],
    entrypoint=["python", "-m", "http.server", "--bind", "::", "8000"],
  )

  # Run the container as an API
  pod.deploy()
  ```
</Card>


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