The Go Development Server

The App Engine SDK for Go includes a local development server that you can run locally to simulate your application running in production App Engine. The simulated environment enforces some sandbox restrictions, such as restricted system functions and Go module imports, but not others, like request time-outs or quotas.

The local development server also simulates the services provided by App Engine Go SDK libraries, including Datastore, Memcache, and Task Queues, by performing their tasks locally. Note that when your application is running in the development server, you can still make remote API calls to the production infrastructure using Google APIs HTTP endpoints.

Running the local development server

Once you have a directory for your application and an app.yaml configuration file, you can start the local development server using the command.


To use the local server directly:

  1. Change to the directory that contains your application's app.yaml configuration file.

  2. Invoke the command: [PATH_TO_YOUR_APP]

    The local server listens on port 8080 by default, so you can visit the application at this URL: http://localhost:8080/. To change which port the local server uses, use the --port option: --port=9999 [PATH_TO_YOUR_APP]

Using goapp serve

To run the development server using the goapp tool included with the App Engine Go SDK:

  1. Change to the directory that contains your application's app.yaml configuration file.

  2. Invoke the command:

     goapp serve

The goapp serve command wraps the underlying python tool provided with the SDK. Note that invoking the python tool directly as gives greater control over the development server: most of the features on this page are features. not working?

Specifying application IDs

If you want to use application IDs with the local development server, don't use the App ID from the APPLICATION_ID environment variable. The development server differs from production App Engine service in that the local server prepends the string dev~ to the APPLICATION_ID environment variable.

Instead, if you need to access your App ID in the local server, for example to spoof an email address, use the appengine.AppID function. To get the hostname of the running app, use the appengine.DefaultVersionHostname function.

Using the local Datastore

The local development server simulates the App Engine datastore using a local file that persists between invocations of the local server.

For more information on indexes and index.yaml, see the Datastore Indexes and Datastore Index Configuration pages.

Browsing the local Datastore

If your app has written data to your local Datastore using the local development server, you can browse it in the local development console.

To browse local Datastore:

  1. Start the development server.

  2. Access the Datastore Viewer in the local development console. (The URL is http://localhost:8000/datastore.)

  3. View your local Datastore contents.

Specifying the ID allocation policy

For production App Engine, you can set the Datastore to automatically generate entity IDs.

Although the auto ID assignment policies for the production server are completely different than those used by the development server, you can also set the automatic ID allocation policy for the local server.

To specify the automatic ID assignment policy, use the --auto_id_policy option: --auto_id_policy=sequential

where --auto_id_policy can be one of the following:

  • scattered: (default) IDs are assigned from a non-repeating sequence of approximately uniformly distributed integers.
  • sequential: IDs are assigned from the sequence of consecutive integers.

Clearing the local Datastore

To clear the local datastore for an application, invoke the local development server as follows: --clear_datastore=yes [PATH_TO_YOUR_APP]

Changing local Datastore location

To change the location used for the datastore file, use the --datastore_path option: --datastore_path=/tmp/myapp_datastore [PATH_TO_YOUR_APP]

Using the Users service

App Engine provides a Users Service to simplify authentication and authorization for your application. The local development server simulates the behavior of Google Accounts with its own sign-in and sign-out pages. While running under the local development server, the LoginURL and LogoutURL functions return URLs for /_ah/login and /_ah/logout on the local server.

Using Mail

The local development server can send email for calls to the App Engine mail service using either an SMTP server or a local installation of Sendmail.

Using SMTP

To enable mail support with an SMTP server, invoke as follows:: --smtp_port=25 \
  --smtp_user=ajohnson --smtp_password=k1tt3ns [PATH_TO_YOUR_APP]

where you set the --smtp_host, --smtp_port, --smtp_user and --smtp_password options with your own values.

Using Sendmail

To enable mail support with Sendmail, invoke as follows: --enable_sendmail=yes

The local server will use the sendmail command to send email messages with your installation's default configuration.

Using URL Fetch

When your application uses the URL fetch API to make an HTTP request, the local development server makes the request directly from your computer. The URL Fetch behavior on the local server may differ from production App Engine if you use a proxy server for accessing websites.

Send feedback about...

App Engine standard environment for Go