Metadata

Encore tries to give your code the same environment wherever it runs, but sometimes it helps to know more: which environment you're in, which cloud it runs on, or where the app can be reached. The encore.env module provides this information.

Application metadata

Call app_meta() to get an AppMeta object describing the running application. It's also available as encore.app_meta().

from encore import env

meta = env.app_meta()
print(meta.app_id, meta.environment.name, meta.environment.type)

The metadata is read on first use, and every later call returns the same object. All the metadata classes are frozen dataclasses.

AppMeta has these attributes:

Environment

meta.environment is an EnvironmentMeta with:

• name: the environment's name. For local development it's "local".
• type: one of "production", "development", "ephemeral" or "test". It's "development" under encore run and "test" under encore test.
• cloud: one of "aws", "gcp", "azure", "encore" or "local". It's "local" for local development.

Gateways

An app can have several API gateways, so there's no single base URL for its API. Look up the gateway you need by name:

gw = env.app_meta().gateways.get("api")
if gw is not None:
    print("api is at", gw.base_url)

Each GatewayMeta has a name and a base_url. Locally, base_url is http://localhost:<port>, typically http://localhost:4000. If the environment uses a custom domain, base_url uses it, but note that it reflects the domain at the time of deployment. A process that serves no gateway, such as a worker, gets an empty dict.

To call another service directly rather than through a gateway, use encore.services.base_url.

Build and deployment

• build.revision: the version control revision the app was built from.
• deploy.id: the deployment's unique ID, generated by Encore Cloud.
• deploy.time: when this build was deployed to the environment, as a timezone-aware datetime.
• deploy.hosted_services: the services this deployment hosts, as a list of HostedService, each with a name.

Example use cases

Behaving differently by environment

Use the environment type rather than its name when behavior should follow the kind of environment, so it keeps working as you add environments:

from encore import env


def send_email(to: str, subject: str, body: str) -> None:
    if env.app_meta().environment.type != "production":
        print(f"email to {to}: {subject}")  # don't email real users outside production
        return
    # ... send it for real

Using cloud-specific services

Encore supports a common set of infrastructure on every cloud. For services it doesn't cover, branch on the cloud the environment runs on. For example, to write audit logs to a data warehouse:

from encore import env


async def write_audit_log(entry: dict) -> None:
    cloud = env.app_meta().environment.cloud
    if cloud == "gcp":
        await write_to_bigquery(entry)
    elif cloud == "aws":
        await write_to_redshift(entry)
    else:
        write_to_file(entry)

For values that differ between environments, prefer configuration over checking the environment in code.