# Local development

In the cloned workspace you start every application with ap run-local, use the runtimes from .tool-versions and follow the rules for generated and custom files, which apply to AI agents as well.

> Source: https://www.application-platform.com/en/docs/local-development/

A cloned project lives under `~/Documents/application-platform/<organization-slug>/<project-slug>/` with one folder per repository; symlinks to `local-configuration` place `AGENTS.md`, `CLAUDE.md`, `.cursor`, `.claude`, `.codex` and `.vscode` next to them. Open the project folder in your editor rather than a single repository; the layout in a [remote workspace]({{< relref "workspaces-overview" >}}) is identical.

## Starting applications

Every application starts from the root of its repository with the same command:

```bash
ap run-local
```

A backend starts Docker services and dev server, an app Flutter Web or its stack's dev server, a homepage Hugo or Astro, each with the env files and on fixed ports (`ap ports`). For Flutter you pass target and device, such as `ap run-local chrome`; `--env dev` loads the dev configuration instead of the local one, and the platform extension's start button runs the same command, see [Starting applications]({{< relref "workspace-ubuntu-dev-scripts" >}}).

## Runtimes via asdf

Runtime versions are pinned per repository in `.tool-versions`; `asdf` manages them on macOS and Linux, FVM, NVM and HVM on Windows. `ap bootstrap` installs them without starting the application, `ap doctor` shows missing tools. Do not install runtimes globally around the project, or your machine builds differently than the pipeline.

## Generated and custom files

The platform writes `env/*.generated.env` and `.gitlab-ci.yml` and overwrites them whenever the project changes; your values go into `env/*.custom.env`, after which you restart `ap run-local`. A pre-commit hook (`ap git pre-commit check`) from the setup app and `clone` blocks commits to the generated files; the individual files and `gitops-configuration` for dev and prod are covered in [Environment variables]({{< relref "environment-setup" >}}). The platform manages passwords, tokens and keys encrypted; they do not belong in `*.custom.env`, commits, logs or chat replies.

## Uploads in the backend

A backend stores persistent file uploads under `./upload` locally and under `/app/upload` in the container, where the server mounts `./backend-uploads`; Multer, FastAPI upload handlers or Laravel Storage point there and not at `user-uploads` or `/app/uploads`. Dockerfiles create the folder with `RUN mkdir -p upload`.

## AGENTS.md as the contract

The `AGENTS.md` from `local-configuration` sums up these rules and requires working in the matching app repository, not in `local-configuration`; all agents read it automatically. You add your own rules there ([Your own rules for AI agents]({{< relref "ai-instructions" >}})); what the pipeline does after the push is covered in [Git workflow and deployment]({{< relref "git-workflow" >}}).