Component runners extend the component framework through an


[](https://fuchsia.dev/docs/glossary#environment)


to provide a runtime for launching new
component instances.

Component manager launches components by sending a request containing
[`ComponentStartInfo`](https://fuchsia.dev/reference/fidl/fuchsia.component.runner#ComponentRunner) to the appropriate runner using the
[`fuchsia.component.runner.ComponentRunner`](https://fuchsia.dev/reference/fidl/fuchsia.component.runner#ComponentRunner) protocol.
The `ComponentStartInfo` contains details about the component's executable and
its


[](https://fuchsia.dev/docs/glossary#namespace)


. The runner manages the component's
execution within the supported runtime.

After starting the component, component manager uses the
[`fuchsia.component.runner.ComponentController`](https://fuchsia.dev/reference/fidl/fuchsia.component.runner#ComponentRunner) protocol provided
in the [`Start`](https://fuchsia.dev/reference/fidl/fuchsia.component.runner#ComponentRunner) request to send execution actions to the runner,
such as stopping the component. The runner chooses how to interpret these
commands as appropriate to the component runtime.

## Providing runner capabilities

To provide a runner capability, a component must declare a `runner`
capability, whose `path` designates a FIDL protocol implementing
[`fuchsia.component.runner.ComponentRunner`](https://fuchsia.dev/reference/fidl/fuchsia.component.runner#ComponentRunner) served from the
component's


[](https://fuchsia.dev/docs/glossary#outgoing-directory)


.

    {
        capabilities: [
            {
                runner: "web",
                path: "/svc/fuchsia.component.runner.ComponentRunner",
            },
        ],
    }

Component manager sends `ComponentRunner/Start` requests to this protocol.
Each request includes a [`ComponentController`](https://fuchsia.dev/reference/fidl/fuchsia.component.runner#ComponentController) channel which
the runner should serve to handle lifecycle events for the component.

## Routing runner capabilities

Components route runner capabilities by [exposing](https://fuchsia.dev/fuchsia-src/concepts/components/v2/capabilities/runner#expose) them to their
parent and [offering](https://fuchsia.dev/fuchsia-src/concepts/components/v2/capabilities/runner#offer) them to their children.

For more details on how the framework routes component capabilities,
see [capability routing](https://fuchsia.dev/docs/concepts/components/v2/capabilities/README#routing).

### Exposing

Exposing a runner capability gives the component's parent access to that
capability:

    {
        expose: [
            {
                runner: "web",
                from: "self",
            },
        ],
    }

You may optionally specify:

- [`as`](https://fuchsia.dev/fuchsia-src/concepts/components/v2/capabilities/runner#renaming)

### Offering

Offering a runner capability gives a child component access to that
capability:

    {
        offer: [
            {
                runner: "web",
                from: "self",
                to: [ "#child-a" ],
            },
        ],
    }

You may optionally specify:

- [`as`](https://fuchsia.dev/fuchsia-src/concepts/components/v2/capabilities/runner#renaming)

## Registering a component runner

Component runners are made available to components through their
[environment](https://fuchsia.dev/docs/concepts/components/v2/environments). To register a new runner within an environment,
add a new entry to the `runners` section of the `environments` declaration:

    environments: [
        {
            name: "my-environ",
            extends: "realm",
            runners: [
                {
                    runner: "web",
                    from: "parent",
                },
            ],
        },
    ]

You may optionally specify:

- [`as`](https://fuchsia.dev/fuchsia-src/concepts/components/v2/capabilities/runner#renaming)

For more details on how to apply environments to components, see the
[environments documentation](https://fuchsia.dev/docs/concepts/components/v2/environments).

## Selecting a runner

A component specifies the appropriate runner for execution using the `program`
section of its manifest. The `program` section designates the `runner` as well
as any runner-specific options. The runner must be [registered](https://fuchsia.dev/fuchsia-src/concepts/components/v2/capabilities/runner#register) in
the component's environment.

For example, a component which runs as a web page might have a `program` like
the following:

    program: {
        runner: "web",
        mode: "incognito",
    },

When the component manager attempts to launch this component, it will send a
request to the provider of the `web` runner to start it.

## Renaming runners

You may `expose`, `offer`, or [register](https://fuchsia.dev/fuchsia-src/concepts/components/v2/capabilities/runner#register) the runner capability under
a different name using the `as` parameter:

    {
        expose: [
            {
                runner: "web",
                from: "#chromium",
                as: "web-chromium",
            },
        ],
    }

## Framework runners

Component framework provides the following built-in component runners:

- [ELF runner](https://fuchsia.dev/docs/concepts/components/v2/elf_runner): Runs binaries compiled to the ELF file format.

    {
        program: {
            runner: "elf",
            binary: "bin/example",
        },
    }

[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/concepts/components/v2/capabilities/runner.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/concepts/components/v2/capabilities/runner.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/concepts/components/v2/capabilities/runner.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/concepts/components/v2/capabilities/runner.md "Edit the source code of this page")