Hello World

Wherein Vanadium says hello!

All tutorials require Vanadium installation, and must run in a bash shell.
Further, please download this script then source it:

source ~/Downloads/scenario-a-setup.sh

This command wipes tutorial files and defines shell environment variables. If you start a new terminal, and just want to re-establish the environment, see instructions here.

If you would like to generate files from this tutorial without the copy/paste steps, download and source this script. Files will be created in the $V_TUT directory.


Practically speaking, Vanadium is a set of Go and Java language libraries (more languages coming), plus a few dozen services and command line tools built on top of them.

The goal of this first tutorial is to get you to running code as quickly as possible. Subsequent tutorials will explain what's happening here in more detail, and take you much further into security and service discovery.

When they do so, the tutorials create files in $V_TUT (likely $HOME/v23_tutorial):

echo $V_TUT

The initial tutorials use Go language examples, but you don't need to know Go to do them.

Since Vanadium is a distributed computing framework, its simplest demo requires two programs - a server and a client.

Make a server

The interface

The following command (read more about cat usage here) creates a Vanadium Definition Language file defining a Hello service:

mkdir -p $V_TUT/src/hello/ifc
 cat - <<EOF >$V_TUT/src/hello/ifc/hello.vdl
package ifc

type Hello interface {
  // Returns a greeting.
  Get() (greeting string | error)

Stub code

Use the hello.vdl file to generate Go code describing the hello interface. It will soon be linked into a client and server.

VDLROOT=$VANADIUM_RELEASE/src/v.io/v23/vdlroot \
    VDLPATH=$V_TUT/src \
    $V_BIN/vdl generate --lang go $V_TUT/src/hello/ifc

You can see the newly generated file here:

ls $V_TUT/src/hello/ifc


The following implements the Hello interface:

mkdir -p $V_TUT/src/hello/service
 cat - <<EOF >$V_TUT/src/hello/service/service.go
package service

import (

type impl struct {

func Make() ifc.HelloServerMethods {
  return &impl {}

func (f *impl) Get(_ *context.T, _ rpc.ServerCall) (
    greeting string, err error) {
  return "Hello World!", nil

Build the server

Service in hand, we need an executable to serve it on the network.

mkdir -p $V_TUT/src/hello/server
 cat - <<EOF >$V_TUT/src/hello/server/main.go
package main

import (
  _ "v.io/x/ref/runtime/factories/generic"

func main() {
  ctx, shutdown := v23.Init()
  defer shutdown()
  _, _, err := v23.WithNewServer(ctx, "", ifc.HelloServer(service.Make()), nil)
  if err != nil {
    log.Panic("Error listening: ", err)
  <-signals.ShutdownOnSignals(ctx)  // Wait forever.
go install hello/server

Your server binary is here:

ls $V_TUT/bin

Make a client

This client is short-lived; it starts, makes a call, then exits.

mkdir -p $V_TUT/src/hello/client
 cat - <<EOF >$V_TUT/src/hello/client/main.go
package main

import (
  _ "v.io/x/ref/runtime/factories/generic"

var (
  server = flag.String(
      "server", "", "Name of the server to connect to")

func main() {
  ctx, shutdown := v23.Init()
  defer shutdown()
  f := ifc.HelloClient(*server)
  ctx, cancel := context.WithTimeout(ctx, time.Minute)
  defer cancel()
  hello, _ := f.Get(ctx)
go install hello/client

Make a principal

All communication in Vanadium is authenticated, meaning both sides must recognize each other's identity. In this initial example we'll cheat a bit - we'll define just one identity (called a principal), then use it for both the client and server.

Create a principal called tutorial:

$V_BIN/principal create \
    --with-passphrase=false \
    --overwrite $V_TUT/cred/basics tutorial

Run your code

Start the server:

PORT_HELLO=23000  # Pick an unused port.
kill_tut_process TUT_PID_SERVER
$V_TUT/bin/server \
    --v23.credentials $V_TUT/cred/basics \
    --v23.tcp.address :$PORT_HELLO &

Run the client to get a hello:

$V_TUT/bin/client \
    --v23.credentials $V_TUT/cred/basics \
    --server /localhost:$PORT_HELLO

That's it - you've built and run your first Vanadium apps.

Clean up

kill_tut_process TUT_PID_SERVER


All of the above and more will be covered in detail in subsequent tutorials.