# Deploy

This page covers how to get an APK onto a Board: building it with Godot’s own Android export, the one-time setup that keeps cold boot fast, and installing it from a browser or with an agent. No build scripts are required for the supported path.

For a quick “build and push” recipe, see [Quick Start](https://docs.dev.board.fun/godot/getting-started/quick-start). For project-setup details, see [Setup Reference](https://docs.dev.board.fun/godot/getting-started/setup-reference).

## Build APK

Build the APK with Godot’s standard Android export — no extra tooling.

- **In the editor:** **Project > Export Project… > Android**, then export to an `.apk`.
- **Headless / CI:**

```
godot --headless --export-debug "Android" out.apk
```

With `gradle_build/use_gradle_build=true` in the Android export preset, this drives the Gradle build, bundles the addon’s `board.aar` (so `libboard.so` is present for the Board’s install gate) and the Piece Set Model into the PCK, and signs with the debug keystore. The model loads from the PCK, so a vanilla export Just Works — there’s no asset-staging step to run.

Use `--export-debug` (or the editor’s debug export) while iterating; build a **release** export (`--export-release`) for distribution — a debug build ships the unstripped Godot engine library (~75 MB on its own), so it’s far larger than a release build.

## One-time setup: keep the PCK uncompressed

After installing Godot’s Custom Android Build Template ( **Project > Install Android Build Template**), open `android/build/build.gradle` and add this line to the `aaptOptions` block, right after the `ignoreAssetsPattern` line:

```
aaptOptions {
    ignoreAssetsPattern "..."
    noCompress "pck", "sparsepck"
}
```

Godot’s stock template doesn’t set this. Without it the PCK is deflated inside the APK, and cold boot takes about two minutes instead of a few seconds because the engine has to inflate it on launch. You only need to do this once per project (re-apply it if you reinstall the build template).

## Install and Launch

The Board exposes Board Connect, its built-in HTTP API, so there’s no USB cable involved. The Board shows its address under **Settings > System**.

### From a browser (human)

1. Open the Board Connect web UI in your browser, using the address shown under **Settings > System** on the Board.
2. Drag your `.apk` onto the page to install it.
3. Launch the game from the Library.

### With an agent (board-connect)

The `board-connect` CLI is the agent-facing Board Connect client — no ADB, no scripts. Install it from [dev.board.fun/connect/install](https://dev.board.fun/connect/install). You only pass the Board’s address to `pair`; that saves it as the default, so every later command resolves the target on its own:

1. `board-connect pair <host>` — run once; the user taps **Approve** on the device.
2. `board-connect install <apk> --launch` — install the exported APK and bring it to the foreground.
3. `board-connect launch <package>` — launch it.
4. `board-connect logs <package>` — tail the app’s logs (add `--follow` to stream live).
5. `board-connect screenshot --out shot.png` — capture the screen.

## Accessing Sideloaded Games on Board

After installation, your game lives under **Settings > Sideloaded Apps** on the Board’s Home screen. Tap your title to launch.

> **Note**: Requires BoardOS 1.10.0 or later.

## Viewing Logs

Stream the app’s logs over Board Connect: from a browser, the Board Connect web UI shows logs for an installed app; with an agent, use `board-connect logs <package> --follow` while the app runs.

## Troubleshooting

### Board Not Detected

| Symptom | Fix |
| --- | --- |
| The web UI or agent can’t reach the Board | Confirm you’re using the Board’s current address from **Settings > System** and that your machine is on the same network (Board Connect listens on port 8843 over the LAN). |
| Pairing fails or is rejected | Re-run `board-connect pair <host>` (pass `--force` to mint a fresh token) and have the user tap **Approve** on the device. The Board’s address is shown under **Settings > System**. |

### Installation Fails

| Symptom | Fix |
| --- | --- |
| `Error: this APK is not built with Board SDK` | The Board’s install gate rejected the APK because it doesn’t contain `lib/arm64-v8a/libboard.so`. The AAR in your addon copy is stale or corrupt — re-copy `addon/addons/board_sdk` from the SDK release into your project’s `addons/` directory and re-export. |
| `Missing <project>/android/build` | Open the project in Godot once and run **Project > Install Android Build Template**. |
| Gradle reports class file version 61 / 65 | Wrong JDK active for the Gradle daemon. Run `./gradlew --stop` and re-run the export with `JAVA_HOME` pointing at JDK 17. |

### App Crashes or Doesn’t Launch

| Symptom | Fix |
| --- | --- |
| Cold boot takes ~2 minutes | The PCK is being inflated on launch. Add `noCompress "pck", "sparsepck"` to the `aaptOptions` block in `android/build/build.gradle` (see [One-time setup](https://docs.dev.board.fun/godot/getting-started/deploy#one-time-setup-keep-the-pck-uncompressed)) and re-export. |
| App launches but `Board.is_on_device` is `false` | The plugin AAR didn’t load. Check the app’s logs for `GodotPluginRegistry` lines — usually a Java version mismatch. JDK 17 must be active for Godot builds. |
| BoardOS Settings shows `godot-project-name` instead of your game name | The display name wasn’t set. Confirm the name/package in the Android export preset, then re-export. |

## Next Steps

- [Quick Start](https://docs.dev.board.fun/godot/getting-started/quick-start) — fastest path to a deployed APK
- [Setup Reference](https://docs.dev.board.fun/godot/getting-started/setup-reference) — every project setting
- [Sample Scene](https://docs.dev.board.fun/godot/getting-started/sample) — walkthrough of the sample app