# Working locally on your project

The setup app prepares your machine and clones all repositories of a project into one shared folder where editors and AI agents see the whole project.

> Source: https://www.application-platform.com/en/docs/working-locally/

Locally, tools and code live on your machine under macOS, Windows, or Linux. The [setup app]({{< relref "local-app" >}}) installs missing tools, clones your projects, and opens them in your editor; the machine requirements are under [Requirements]({{< relref "local-requirements" >}}). Without installing anything, you work the same way in a [remote workspace]({{< relref "workspaces-overview" >}}), a prepared Ubuntu VM in the cloud.

## How the setup goes

You download the setup app from the [downloads page]({{< relref "/downloads" >}}), sign in with your Application Platform account, and run the **Developer setup**, which installs whatever is missing, from Git and the runtimes to the `ap` CLI. Then you clone a project in the **Projects** area; the app fetches all repositories, creates the shared configuration, and opens the project in your editor or AI tool with a click.

## The project folder

All repositories of a project sit under `~/Documents/application-platform/<organization>/<project>/`: one directory per component, `local-configuration` for editors and AI agents, and `gitops-configuration` for deployment.

```
~/Documents/application-platform/<organization>/<project>/
├── backend/                 # one folder per repository
├── <app>/
├── homepage/
├── local-configuration/     # shared editor and agent configuration
├── gitops-configuration/    # deployment configuration
├── AGENTS.md → local-configuration/AGENTS.md
├── CLAUDE.md → local-configuration/CLAUDE.md
├── .cursor   → local-configuration/.cursor
├── .claude   → local-configuration/.claude
├── .codex    → local-configuration/.codex
├── .vscode   → local-configuration/.vscode
└── …
```

The entries pointing to `local-configuration` are symlinks created by the setup app when cloning; the same editor settings and [rules for AI agents]({{< relref "ai-instructions" >}}) therefore apply to every repository. Always open this project folder in your editor or AI agent, not a single repository, so backend, app, and homepage are visible together and the shared configuration applies.

## Working in the project

You start each application from its repository root with `ap run-local`, which depending on the type starts Docker services and a development server, Flutter web, or Hugo with the matching environment files; ports, stopping, and typical errors are covered in [Starting applications]({{< relref "workspace-ubuntu-dev-scripts" >}}). Runtime versions are pinned per repository in `.tool-versions`, provided by `asdf` on macOS and Linux and by FVM, NVM, and HVM on Windows. Configuration values live in `env/*.generated.env` (platform) and `env/*.custom.env` (your own values), see [Environment variables]({{< relref "environment-setup" >}}); a push to `main` starts the pipeline from [Git workflow and deployment]({{< relref "git-workflow" >}}).