The [`ffx repository`](https://fuchsia.dev/reference/tools/sdk/ffx#repository) commands can create and manage
Fuchsia package repositories on the host machine.

## Concepts

When a Fuchsia device needs to run new software or update existing software,
the device requests and downloads [Fuchsia packages](https://fuchsia.dev/docs/concepts/packages/package) from
a [Fuchsia package server](https://fuchsia.dev/docs/concepts/packages/fuchsia_package_server), which is a service
that you can run on your host machine. The Fuchsia package server
then serves Fuchsia packages from
a [Fuchsia package repository](https://fuchsia.dev/fuchsia-src/development/tools/ffx/workflows/create-a-package-repository#create-a-package-repository) configured
on the host machine.

A Fuchsia package repository is mapped to a directory on the host machine.
When handling requests from Fuchsia devices, the Fuchsia package server looks
for Fuchsia packages in this directory. If they're found, the package server
serves the packages to the devices directly from this directory. Therefore,
this directory on the host machine is where you'll want to store your
in-development Fuchsia packages for target devices.

Once a new Fuchsia package repository is created, you need to register the
package repository to your Fuchsia device (or devices), which permits the device
to download Fuchsia packages from this package repository. Fuchsia devices can
only download Fuchsia packages from their registered Fuchsia package repositories.

Lastly, you can set up the Fuchsia package server to serve from multiple Fuchsia
package repositories on the same host machine, where you may dedicate each package
repository for a specific purpose (for instance, to separate stable packages
from experimental packages).

## Create a package repository

To create and set up a new package repository on your host machine,
do the following:

1. Create a new repository:

       ffx repository create <REPOPATH>

   Replace `REPO_PATH` with the directory path for the new repository.

   However, there is no check for existing contents in that directory,
   so make sure that the directory does not exist before running this
   command.
2. (Optional) Set the default name for the repository:

       ffx repository default set <REPO_NAME>

   Replace `REPO_NAME` with the name of a package repository,
   for example:

       ffx repository default set my-repo

   This is typically not needed since the build directory level
   configuration of `ffx` already contains the correct value.

   After setting the default repository, this command exits silently
   without output.

## Start a Fuchsia package server

To be able to serve packages from Fuchsia package repositories
on your host machine, a Fuchsia package server must be running
on the machine.

To start a new Fuchsia package server, run the following command:

    ffx repository server start --foreground  --repo-path <REPO_PATH>

Replace `REPO_PATH` with the path to a product bundle on your host machine,
for example:

    $ ffx repository server start --foreground  --repo-path ~/my-product-bundle

Also, notice that this command starts the package server in the foreground
(`--foreground`). This means the server's log messages will be printed to
the terminal window. Alternatively, you can start the package server in the
background by using the `--background` option. In this case, the log messages
will be stored in the `${log.dir}/repo-REPO_NAME.log` file. For more options,
see [Start package servers](https://fuchsia.dev/fuchsia-src/development/tools/ffx/workflows/start-package-servers).

## Start a Fuchsia package server using a product bundle

To serve packages from an existing product bundle, you need to download the
product bundle and start the package server using the product bundle.

Do the following:

1. View the list of available products:

       ffx product list

2. Download your desired product bundle:

       ffx product download <PRODUCT> <DOWNLOAD_DIR>

   Replace the following:
   - `PRODUCT_NAME`: The product name of your target Fuchsia device.
   - `DOWNLOAD_DIR`: The directory where you want to download the product bundle.

   For example:

       S ffx product download core.x64 ~/Downloads/product-bundles/

3. Start the Fuchsia package server:

       ffx repository server start --background --product-bundle <DOWNLOAD_DIR>

   Replace `DOWNLOAD_DIR` with the directory that contains a product bundle,
   for example:

       $ ffx repository server start --background  --product-bundle ~/Downloads/product-bundles

   You can confirm it is a product bundle directory by checking the presence
   of `product.bundle.json` file in the directory. For more information, see
   [Start package servers](https://fuchsia.dev/fuchsia-src/development/tools/ffx/workflows/start-package-servers).

## Register a package repository to a Fuchsia device

Once the package server is running, you need to register the server address
to the target device.

Do the following:

1. Enable your Fuchsia device to connect to the new repository:

       ffx target repository register [-r <REPO_NAME>] --alias fuchsia.com --alias chromium.org

   Replace `REPO_NAME` with the name of the repository that you want the
   Fuchsia device to connect to.

   If the `-r` flag is not specified, the command selects the default repository.
   For example, thiscommand sets your current Fuchsia device to connect to the
   default repository (`my-repo`) at `fuchsia.com`:

       $ ffx target repository register --alias fuchsia.com --alias chromium.org

   After registering the repository, this command exits silently without output.
2. Verify that the new repository is registered:

       ffx target repository list

   This command prints output similar to the following:

       $ ffx target repository list
       REPO                  URL                              ALIASES
       fuchsia-pkg://default ["http://10.0.2.2:8083/my-repo"] ["fuchsia.com", "chromium.org"]

## Deregister a package repository

To deregister a Fuchsia package repository from the device,
run the following command:

    ffx target repository deregister [-r <REPO_NAME>]

Replace `REPO_NAME` with the name of a registered repository,
for example:

    $ ffx target repository deregister -r my-repo

If the `-r` option is not specified, the command selects the default
repository.

## Stop a Fuchsia package server

To stop a running Fuchsia package server, run the following command:

    ffx repository server stop

This command prints output similar to the following:

    $ ffx repository server stop
    server stopped

For more options, see
[Stop running package servers](https://fuchsia.dev/fuchsia-src/development/tools/ffx/workflows/stop-package-servers).
[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/development/tools/ffx/workflows/create-a-package-repository.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/development/tools/ffx/workflows/create-a-package-repository.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/development/tools/ffx/workflows/create-a-package-repository.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/development/tools/ffx/workflows/create-a-package-repository.md "Edit the source code of this page")