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

# Build Agents

> Configure, secure, and deploy your AI agent.

The `@cycls.app()` decorator is your main interface for configuring dependencies, authentication, and deployment settings. Write a function, decorate it, and Cycls handles the rest.

Here is a full example of an agent configuration:

```python theme={null}
import cycls

@cycls.app(
    pip=["openai", "pandas"],       # Python packages to install
    apt=["ffmpeg"],                 # System packages via apt
    copy=["data.csv", ".env"],      # Local files to bundle
    copy_public=["logo.png"],       # Public assets (images, etc.)
    auth=True                       # Enable authentication
)
async def app(context):
    # Your agent logic here
    yield "Hello! I am ready to help."

# Run locally for development
app.local()
```

## Deployment Modes

### Local Development (`app.local()`)

Running `app.local()` builds a portable Docker image containing your agent and all dependencies. The image includes a pre-configured **FastAPI** server that serves the REST API and the web interface.

<Note>
  **Requirement:** You must have [Docker](https://www.docker.com/) installed and running.
</Note>

```python theme={null}
app.local()
```

You will see the build logs and your local URL:

```bash theme={null}
Successfully built de0e95b9ae6d
Successfully tagged cycls/app:52afe9dc9be77162
----------------------------------------
✅ Base image built successfully
--- 🪵 Container Logs (streaming) ---
🔨 Visit app => http://localhost:8080
INFO:     Started server process [1]
INFO:     Application startup complete.
```

* **Result:** A locally running Docker container serving your agent.
* **Hot Reload:** By default, the server watches for file changes and restarts automatically.
* **Portability:** You can take this image and deploy it to any cloud provider or on-premise server.
* **URL:** `http://localhost:8080`

#### Development Options

```python theme={null}
# Standard development with hot-reload
app.local()

# Disable file watching
app.local(watch=False)
```

### Cloud Deployment (`app.deploy()`)

Running `app.deploy()` auto-builds your agent and deploys it to Cycls' serverless infrastructure in a single command.

```python theme={null}
import cycls
import os

# Set your API key
cycls.api_key = os.getenv("CYCLS_API_KEY")

@cycls.app(pip=["openai"])
async def app(context):
    yield "Hello from the cloud!"

app.deploy()
```

* **Result:** A live, auto-scaling API and web interface.
* **Features:** Managed SSL, built-in auth, global CDN.
* **URL:** `https://<app-name>.cycls.ai`

## Configuration Reference

### `@cycls.app()` Decorator

The decorator transforms your function into a deployable agent with all configuration in one place.

<ResponseField name="@cycls.app" type="Decorator">
  <Expandable title="parameters" defaultOpen="true">
    <ResponseField name="pip" type="list[string]">
      List of Python package names to install (e.g., `["openai", "pandas"]`).
    </ResponseField>

    <ResponseField name="apt" type="list[string]">
      System-level dependencies to install via apt (e.g., `["ffmpeg"]`).
    </ResponseField>

    <ResponseField name="copy" type="list[string]">
      List of local files or directories to bundle with your agent (e.g., `[".env", "data"]`).
    </ResponseField>

    <ResponseField name="copy_public" type="list[string]">
      List of local files to copy to the public assets folder (e.g., `["logo.png"]`). Accessible via `/public` endpoint.
    </ResponseField>

    <ResponseField name="auth" type="boolean">
      If `True`, enables built-in user authentication (Sign in with Google/Email). Default is `False`.
    </ResponseField>

    <ResponseField name="plan" type="string">
      Set to `"cycls_pass"` to enable Cycls Pass monetization with automatic feature gating.
    </ResponseField>
  </Expandable>
</ResponseField>

### `app.local()`

<ResponseField name="app.local" type="Method">
  <Expandable title="parameters" defaultOpen="true">
    <ResponseField name="watch" type="boolean">
      * `True` (default): Enables hot-reload, automatically restarting on code changes.
      * `False`: Runs without file watching.
    </ResponseField>
  </Expandable>
</ResponseField>

### `app.deploy()`

Deploys your agent to the Cycls cloud. Requires `cycls.api_key` to be set.

```python theme={null}
import cycls
cycls.api_key = "your-api-key"

app.deploy()
```

## Next Steps

<Card title="Manage Context" horizontal href="/core-concepts/context">
  Learn how to use context to access conversation history.
</Card>