---
layout: docs
page_title: Entrypoint
description: |-
  Waypoint uses an entrypoint binary to enable features such as application configuration, logs, exec, and more.
---

# Waypoint Entrypoint

Waypoint uses an entrypoint binary to enable features such as application
configuration, logs, exec, and more. In most cases, Waypoint will automatically
inject and configure the entrypoint binary during the build phase. The
image below shows a high-level architecture diagram of the entrypoint in
a Docker image.

![Entrypoint Overview](/img/entrypoint-overview.png)

~> The entrypoint binary injection and usage is **not required** and can be
disabled. This will also disable features such as logs, exec, etc. for that
application. See [disabling the entrypoint](/docs/entrypoint/disable) for more information.

## Installation

**For builders that produce Docker images, the entrypoint is automatically
injected into the container image.**

For other types of builds, the entrypoint must be manually installed.
To manually install the entrypoint:

1. [Download](https://releases.hashicorp.com/waypoint-entrypoint/) the appropriate `waypoint-entrypoint` binary for the
   platform your application will run on. This is _not_ your desktop operating
   system but the operating system your app will be deployed _to_.

2. Put the single binary Waypoint entrypoint anywhere in your deployment
   image, such as `/usr/local/bin` on Unix-like systems.

3. Configure your application startup to run the entrypoint first rather
   than your application. If you booted your application as
   `node app.js`, change that to `waypoint-entrypoint /usr/bin/node app.js`

-> Builder-specific documentation for entrypoint injection will be
written soon. The instructions above are the most generic and we understand
they may be complicated to apply to your builder.

## Functionality

The features listed below require the entrypoint. If you choose to
disable the entrypoint, the features below will not work. The entrypoint
can be disabled on a per-project or per-application basis, so you can
choose to opt-out of the functionality below for only some of your
applications.

- URL Service
- Application configuration
- Exec (`waypoint exec`)
- Logs (`waypoint logs`)
- Instance tracking

More features that require the entrypoint may be introduced in the future.

## Resource Requirements

The Waypoint entrypoint introduces some small amount of overhead to your
deployments.

The primary resource requirement for the entrypoint is a small amount of RAM.
The CPU impact is negligible since the entrypoint mostly sits idle. No disk
access is required at all. We haven't yet measured the exact usage but plan to soon.

The entrypoint primarily sits idle waiting on network traffic. The entrypoint
will only "wake up" from blocking on network traffic when it receives new
application configuration, a request for `exec`, an inbound request from the
URL service, etc.

## Logging

The entrypoint itself emits logs about its own behavior. These logs are
in addition to the logs emitted by the deployed application. We differentiate
between the two by calling one "entrypoint logs" and the other "application
logs".

Entrypoint logs are also streamed and can be viewed via `waypoint logs`. If
`waypoint logs` is not working, the entrypoint logs are also emitted to stderr.
This is primarily for debugging purposes in case the entrypoint is not
functioning properly.

The default log level for entrypoint logs is `DEBUG`. You may change the
log level by setting the `WAYPOINT_LOG_LEVEL` environment variable to
one of: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR` (values further to the
left are more verbose than those to the right). This environment variable
may be set at build time, using deployment plugin configuration, or
via the [waypoint config CLI](/docs/app-config#setting-configuration-via-the-cli).

-> **Note:** The `WAYPOINT_LOG_LEVEL` environment variable must be set
within the runtime environment of your deployment, not on your local machine.
This is a common error when attempting to change entrypoint log levels.

## Failure Behavior

The Waypoint entrypoint is designed to be resilient to failure scenarios
that it introduces.

### Server Unavailable on Startup

If the Waypoint server connection cannot be established on startup
within 5 seconds, Waypoint will "fail open" by starting the child
process immediately. Waypoint will continue to retry to connect to the
server in the background.

This behavior allows Waypoint to start the child process no matter what.

If you're using [application configuration](/docs/app-config), the configuration
will not be available to the application in this failure case. This may
cause the application startup to fail.

### Server Connection Lost

If the Waypoint server connection is lost at any point during runtime,
the child process is unaffected. Waypoint will retry to establish a
connection in the background.

While the connection is lost, any entrypoint related functionality will
stop working. Initial application configuration will be retained, but
further application configuration changes will have no effect until the
connection can be reestablished.

During this time, logs will be dropped. The application logs during the period
when the connection was lost will not become available again. Once the
connection is re-estalished, new logs from that point forward will be sent
to the server.

## Security

The Waypoint entrypoint _does not_ open any network listeners. It _does not_
proxy any network connections to your application except for the URL service
(which is an outbound connection, not inbound). When a user visits your
application using your release URL (such as directly via a Kubernetes
Service for example), the traffic is routed directly to the application.

The Waypoint entrypoint _does_ maintain a long-running outbound connection
to the Waypoint server as well as the Waypoint URL service (if enabled).
Most importantly for security, the Waypoint server can initiate an
`exec` call to arbitrarily execute commands within the context of your
application. Therefore it is important that the server is well secured.

The Waypoint entrypoint connects to the Waypoint server using a token
that can only retrieve and set entrypoint-related information for that
specific deployment. It cannot trigger new deploys, list existing deploys,
etc. Therefore, if the environment the entrypoint is running in is compromised
in any way, it poses a minimal risk to Waypoint as a whole.

The Waypoint entrypoint can be [completely disabled](/docs/entrypoint/disable)
if that is desired. This will disable all entrypoint-related functionality
including app config, logs, exec, etc. You may also
[disable specific features](/docs/entrypoint/disable#disabling-specific-features)
instead of the entire entrypoint.

-> Many improvements are planned to improve the security of the entrypoint.
We plan on restricting the commands that can be used with `exec`, we plan
on supporting more fine-grained feature enable/disable flags, etc.
