> ## Documentation Index
> Fetch the complete documentation index at: https://flatfileinc-remove-rss-json.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploying

> npx flatfile deploy

<Snippet file="shared/dxpbanner.mdx" />

For a production deployment, listeners can be hosted either in your cloud or
directly on the Flatfile platform.

## Flatfile-Hosted Agents  (Recommended)

While your own cloud provides the maximum level of control over listener code,
qualities such as availability and network performance are the responsibility of
the hosting provider. Flatfile offers tooling to deploy and manage Listeners securely hosted
and run in the Flatfile cloud giving you a more consistent, low-latency, high-availability
experience.

### Deploying An Agent

Once you have configured your a local configuration running, bundling and deploying
your listener to the flatfile cloud can be done in a single command.

```
npx flatfile deploy
```

The CLI will attempt to locate the entrypoint of your listener in the following order:

* `./index.js,`
* `./index.ts`
* `./src/index.js`
* `./src/index.ts`

If your listener is in another location you can provide the path as an argument:

```
npx flatfile deploy ./path-to/listener.ts
```

The CLI will provide updates as it's deploying:

```terminal theme={"system"}
> npx flatfile deploy
✔  Code package compiled to .flatfile/build.js
✔  Code package passed validation
✔  Environment "production" selected
✔  Event listener deployed and running on your environment "production". us_ag_1234
```

<Tip>
  Set your target environment `FLATFILE_ENVIRONMENT_ID` and API token `FLATFILE_API_KEY` in your .env file to avoid entering them when prompted.
</Tip>

### CI Mode

When running deployments in CI/CD pipelines or other automated environments, you can use the `--ci` flag to disable any interactive prompts:

```
npx flatfile deploy --ci
```

In CI mode:

* No confirmation prompts will be displayed
* The command will fail with a clear error message if multiple agents exist and no slug is provided
* TypeScript configuration checks will be skipped

This is particularly useful for automated deployments where user interaction isn't possible.

### Dashboard Management

You can view and manage agents via the Flatfile Dashboard. The dashboard provides a simple interface for monitoring and controlling your deployed agents with the following capabilities:

| Feature               | Description                                                                                         |
| --------------------- | --------------------------------------------------------------------------------------------------- |
| View Agent            | Access details about your deployed agents including their latest deployment and last received event |
| View Logs             | Monitor agent activity and troubleshoot issues by examining execution logs                          |
| Download Agent Code   | Retrieve the deployed code for reference, backup, or refactoring purposes                           |
| Delete Agent          | Remove agents that are no longer needed from your environment                                       |
| Revert Agent          | Roll back to a previous version if issues arise with newer deployments                              |
| Deploy Library Agents | Deploy pre-built agents from the Flatfile Agent Library                                             |

### Re-Deploying

To update the code in your listener simply make the update your desire re-deploy.
Agents are versioned and you may revert to a previous version at any time via the dashboard.

### Multiple Agents

To deploy a second Agent without overwriting the first, specify a unique slug:

```terminal theme={"system"}
npx flatfile deploy -s pink
```

When you pass a slug, the CLI will create a new Agent with the specified
slug. This allows you to deploy multiple Agents to the same environment.

To update an existing Agent, you can specify the slug of the Agent you want to
update by running the same command, including the slug.

<Note>
  If you do not specify a slug and have only one or no deployed Agents the CLI
  will update your existing Agent, or create your first Agent. The slug for this
  agent will be `default`.
</Note>

## Hosting on Regional Servers

<Tip>
  To deploy on a regional server, please contact our support team.
</Tip>

Regional servers are available upon request for those needing to host their
applications closer to their user base, ensuring faster access and compliance
with local data regulations.

### URL References

| Region | URL / SPACE\_URL         | API URL                      |
| ------ | ------------------------ | ---------------------------- |
| UK     | platform.uk.flatfile.com | platform.uk.flatfile.com/api |
| EU     | platform.eu.flatfile.com | platform.eu.flatfile.com/api |
| AU     | platform.au.flatfile.com | platform.au.flatfile.com/api |
| CA     | platform.ca.flatfile.com | platform.ca.flatfile.com/api |

### Configuring API URL

When deploying, you can specify the `FLATFILE_API_URL` either in your project's
`.env` file or as an environment variable.

<CodeGroup>
  ```bash .env theme={"system"}
  FLATFILE_API_URL=platform.eu.flatfile.com
  ```
</CodeGroup>

### Embedding Via Space URL

To embed Flatfile in your application, include both apiUrl and spaceUrl in your
FlatfileImporter configuration to specify your regional server:

```typescript theme={"system"}
const spaceProps: ISpace = {
  name: "Embedded Space",
  publishableKey: "pk_**********",
  apiUrl: "Regional API URL here",
  spaceUrl: "Regional Space URL here",
  workbook,
  listener,
  // Additional properties here
};
```

### Configure API Client Environment

For direct API interactions, the FlatfileClient needs the environment parameter
set to your selected regional API URL:

```ts theme={"system"}
import { FlatfileClient } from "@flatfile/api";

const api = new FlatfileClient({
  environment: "Regional API URL here",
});
```

## Self-Hosting

Hosting listener code in your own cloud works similarly to how we run the
`develop` command in that:

1. The listener process is launched
2. It polls the Flatfile API for updates
3. It then responds to those Events accordingly

Reach out to support for learning how about hosting in your own cloud.

## Related Commands

* [develop](/documentation/core-libraries/cli/develop) - Run a local listener for development
* [list](/documentation/core-libraries/cli/agent-management#listing-agents) - List all deployed agents in your environment
* [download-agent](/documentation/core-libraries/cli/agent-management#downloading-agents) - Download an agent from your environment
* [delete](/documentation/core-libraries/cli/agent-management#delete-an-agent) - Delete an agent from your environment