Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 37 ยท Capabilities and Sessions

Server Arguments and Config Files

Control the Appium server with command line flags and a config file: address, port, logging, base path, default capabilities, allowed features and security options.

Capabilities configure one session. Server arguments configure the Appium server itself: where it listens, how much it logs, which drivers and plug-ins load, and which risky features are allowed. For anything beyond a quick experiment you will keep these arguments in a config file, so every machine starts the server the same way.

This lesson shows the most useful server options, the config file format, how precedence works and the security switches you must understand before running Appium on a shared network.

Command line arguments

Run appium server --help to see everything your version supports. The ones you will use most:

Argument Meaning
--address, -a IP to listen on (default 0.0.0.0)
--port, -p Port (default 4723)
--base-path, -pa URL prefix for all routes (default empty, i.e. /)
--log-level error, warn, info, debug, trace
--log, -g Write the log to a file
--log-timestamp, --local-timezone Add timestamps to log lines
--use-drivers Only load the listed drivers
--use-plugins Enable the listed plug-ins
--default-capabilities JSON merged into every new session's capabilities
--session-override Let a new session replace an existing one on the same device
--allow-cors Allow browser-based clients such as hosted Inspector
--config Path to a config file

Examples:

Terminal
appium server --address 127.0.0.1 --port 4725 --log-level debug --log appium.log
appium --use-drivers=uiautomator2 --use-plugins=images
appium --default-capabilities '{"appium:newCommandTimeout": 180}'

Older tutorials write --base-path /wd/hub. Appium 2 changed the default to /, so clients should connect to http://host:4723 unless you set a base path. If you see "unknown command" 404 errors, check that the client URL and server base path agree.

The config file

Instead of long command lines, create a file. Appium looks for .appiumrc.json (also .yaml, .yml, .js, .cjs) in the current directory, or you can name it with --config. The server section mirrors the arguments, using camel case.

JSON
{
  "server": {
    "address": "127.0.0.1",
    "port": 4723,
    "log-level": "info",
    "log-timestamp": true,
    "use-drivers": ["uiautomator2", "xcuitest"],
    "default-capabilities": {
      "appium:newCommandTimeout": 180,
      "appium:autoGrantPermissions": true
    }
  }
}

Check the format your version expects with appium server --help or the config schema in the documentation, because key spelling (kebab-case or camelCase) is validated, and a mistake produces a clear error message at startup. Commit the file to the repository so CI and developers share it.

Precedence

When the same option is set in several places, the more specific one wins:

  1. Command line arguments (highest)
  2. Config file
  3. Built-in defaults (lowest)

This lets a CI job override one value, such as the port, without editing the shared file.

Default capabilities

default-capabilities are merged into each session request. Session capabilities override the defaults for the same key. This is a good place for settings you want everywhere but easily forget, such as newCommandTimeout, and a bad place for app paths or device ids.

Security switches

Appium has powerful features that are disabled by default because they can expose the host:

  • --allow-insecure and --deny-insecure take feature names such as adb_shell, which enables mobile: shell commands that run adb shell commands on the device. Features can be scoped to one driver with uiautomator2:adb_shell.
  • --relaxed-security turns on all insecure features at once. Use it only on an isolated local machine, never on a shared server.
Terminal
appium --allow-insecure=uiautomator2:adb_shell,uiautomator2:chromedriver_autodownload

If a command fails with a message that a feature is not enabled and names it, this is the cause. Enable the exact feature, not everything.

Also remember network exposure: with the default --address 0.0.0.0, any machine that can reach port 4723 can drive your device. On a shared network, bind to 127.0.0.1, put the server behind a firewall or an authenticated reverse proxy, or run it in a container on a private network.

Running several servers

Parallel setups often run one server per device, each on its own port, which isolates crashes. The ports must be distinct, and each session must also use distinct driver ports (systemPort for Android UiAutomator2, wdaLocalPort for iOS).

Merge and validate in a stand-in

A stand-in can model precedence and the feature-flag check. The first block merges three sources into final settings; the second decides whether a command is allowed.

JS Stand-in: merge defaults, config file and CLI

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Stand-in: insecure feature gate

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The model's feature names mirror the real adb_shell flag; which commands need which feature is defined by each driver, so consult its documentation.

Checklist for a team server

  • Config file committed to the repo, with log-level suitable for CI (info; use debug only when investigating).
  • Address bound to localhost, or the network protected.
  • use-drivers limited to what you need, which starts faster and reduces surprises.
  • Logs written to a file that CI uploads as an artifact on failure.
  • Insecure features enabled by name, only for the drivers that need them.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which has the highest precedence when the same server option is set in three places?

    Command line arguments override the config file, which overrides defaults.
  2. 2. What does --default-capabilities do?

    It supplies server-wide defaults; any capability in the session request overrides the same key.
  3. 3. A command fails saying the adb_shell feature is not enabled. What is the safest fix?

    Enable the exact feature for the exact driver instead of switching everything on.
  4. 4. Why bind the server to 127.0.0.1 by default?

    The server is a remote control for devices, so keep it off untrusted networks.

Summary

  • Server arguments configure address, port, logging, drivers, plug-ins and security.
  • A config file keeps those settings in version control; the command line overrides it.
  • Default capabilities apply to every session but are overridden by the session's own.
  • Insecure features are off by default; enable specific ones, never everything on shared hosts.
  • Run one server per device when you need strong isolation in parallel runs.

Next: Locator Strategies